From 429cf68301081b04000fff32362e54cbcc2db96f Mon Sep 17 00:00:00 2001
From: Lindsay M <126139086+lindsaym-fa@users.noreply.github.com>
Date: Fri, 27 Jun 2025 16:27:28 -0400
Subject: [PATCH] Restore docs indices (#1085)

* fix missing indices

* fix search placeholder
---
 .../webawesome/docs/_includes/sidebar.njk     |  4 +-
 .../webawesome/docs/assets/styles/docs.css    | 20 +++++-
 packages/webawesome/docs/docs/layout.njk      | 41 ++++++++++++
 packages/webawesome/docs/docs/tokens/index.md |  7 --
 .../webawesome/docs/docs/tokens/index.njk     | 43 ++++++++++++
 .../webawesome/docs/docs/tokens/tokens.json   |  3 +
 .../docs/docs/utilities/align-items.md        |  1 +
 .../webawesome/docs/docs/utilities/cluster.md |  1 +
 .../webawesome/docs/docs/utilities/color.md   |  1 +
 .../webawesome/docs/docs/utilities/flank.md   |  1 +
 .../webawesome/docs/docs/utilities/fouce.md   |  1 +
 .../webawesome/docs/docs/utilities/frame.md   |  1 +
 .../webawesome/docs/docs/utilities/gap.md     |  1 +
 .../webawesome/docs/docs/utilities/grid.md    |  1 +
 .../webawesome/docs/docs/utilities/index.md   | 21 ------
 .../webawesome/docs/docs/utilities/index.njk  | 66 +++++++++++++++++++
 .../webawesome/docs/docs/utilities/native.md  |  1 +
 .../docs/docs/utilities/rounding.md           |  1 +
 .../webawesome/docs/docs/utilities/split.md   |  1 +
 .../webawesome/docs/docs/utilities/stack.md   |  1 +
 .../webawesome/docs/docs/utilities/text.md    |  1 +
 .../docs/docs/utilities/visually-hidden.md    |  1 +
 22 files changed, 187 insertions(+), 32 deletions(-)
 delete mode 100644 packages/webawesome/docs/docs/tokens/index.md
 create mode 100644 packages/webawesome/docs/docs/tokens/index.njk
 create mode 100644 packages/webawesome/docs/docs/tokens/tokens.json
 delete mode 100644 packages/webawesome/docs/docs/utilities/index.md
 create mode 100644 packages/webawesome/docs/docs/utilities/index.njk

diff --git a/packages/webawesome/docs/_includes/sidebar.njk b/packages/webawesome/docs/_includes/sidebar.njk
index ff10c4f8f..5dfd2c1fc 100644
--- a/packages/webawesome/docs/_includes/sidebar.njk
+++ b/packages/webawesome/docs/_includes/sidebar.njk
@@ -315,8 +315,8 @@
   </ul>
 </wa-details>
 
-<!-- Color Palettes & Themes -->
-<h2>Color Palettes &amp; Themes</h2>
+<!-- Theming -->
+<h2>Theming</h2>
 <ul>
   <li><a href="/docs/color-palettes">Color Palettes</a></li>
   <li><a href="/docs/themes">Themes</a></li>
diff --git a/packages/webawesome/docs/assets/styles/docs.css b/packages/webawesome/docs/assets/styles/docs.css
index 97c21efac..d45359646 100644
--- a/packages/webawesome/docs/assets/styles/docs.css
+++ b/packages/webawesome/docs/assets/styles/docs.css
@@ -99,7 +99,7 @@ wa-page > header {
 #sidebar,
 #outline {
   h2 {
-    font-size: var(--wa-font-size-m);
+    font-size: var(--wa-font-size-s);
     margin: 0;
   }
 
@@ -108,7 +108,16 @@ wa-page > header {
   }
 
   wa-details {
-    --spacing: var(--wa-space-xs);
+    --spacing: 0;
+
+    &::part(header) {
+      padding: 0;
+      padding-block-start: var(--wa-space-xs);
+    }
+
+    &::part(content) {
+      padding-block-start: var(--wa-space-m);
+    }
 
     &::part(base) {
       border: none;
@@ -171,6 +180,7 @@ wa-page > header {
 
 /* Pro badges */
 wa-badge.pro {
+  color: white;
   background-color: var(--wa-brand-orange);
   border-color: var(--wa-brand-orange);
 }
@@ -405,6 +415,7 @@ wa-page > main:has(> .search-list) {
 
     wa-card {
       --spacing: var(--wa-space-m);
+      box-shadow: none;
 
       [slot='header'] {
         display: flex;
@@ -417,6 +428,11 @@ wa-page > main:has(> .search-list) {
         justify-content: center;
         min-block-size: calc(6rem + var(--spacing));
       }
+
+      &:hover {
+        border-color: var(--wa-color-brand-border-loud);
+        box-shadow: 0 0 0 0.0625rem var(--wa-color-brand-border-loud);
+      }
     }
   }
 }
diff --git a/packages/webawesome/docs/docs/layout.njk b/packages/webawesome/docs/docs/layout.njk
index e9223dce3..7f5ee2f18 100644
--- a/packages/webawesome/docs/docs/layout.njk
+++ b/packages/webawesome/docs/docs/layout.njk
@@ -4,6 +4,46 @@ description: Layout components and utility classes help you organize content tha
 layout: docs
 ---
 
+<p>
+{% markdown %}
+  {{ description }}
+{% endmarkdown %}
+</p>
+
+<div class="search-list">
+  <wa-input class="search-list-input" type="search" placeholder="Search layout utilities" autofocus>
+    <wa-icon name="search" slot="start"></wa-icon>
+  </wa-input>
+
+  <section class="search-list-grid">
+    {% for page in collections.layoutUtilities | sort(false, false, 'data.title') %}
+      <a href="{{ page.url }}">
+        <wa-card with-header="" appearance="outlined">
+          <div slot="header">
+            {# Look for an icon based on the page name #}
+            {% set iconPath = "svgs/layout/" + page.fileSlug + ".njk" %}
+            {% set iconContent %}{% include iconPath ignore missing %}{% endset %}
+            {% if iconContent.trim() %}
+              {# An icon exists! Show it #}
+              {{ iconContent | safe }}
+            {% else %}
+              {# Fallback to the placeholder #}
+              {% include 'svgs/thumbnail-placeholder.njk' %}
+            {% endif %}
+          </div>
+          <span class="page-name">{{ page.data.title }}</span>
+        </wa-card>
+      </a>
+    {% endfor %}
+  </section>
+  <div class="search-list-empty" hidden>
+    No results found
+  </div>
+</div>
+
+<wa-divider style="--spacing: var(--wa-space-3xl);"></wa-divider>
+
+<div class="max-line-length">
 {% markdown %}
 ## Installation
 
@@ -21,3 +61,4 @@ Or, you can choose to import _only_ the utilities:
 <link rel="stylesheet" href="{% cdnUrl 'styles/utilities.css' %}" />
 ```
 {% endmarkdown %}
+</div>
diff --git a/packages/webawesome/docs/docs/tokens/index.md b/packages/webawesome/docs/docs/tokens/index.md
deleted file mode 100644
index 18ee9b834..000000000
--- a/packages/webawesome/docs/docs/tokens/index.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-title: Design Tokens
-description: These custom properties thread through all of Web Awesome's components, giving things a consistent look and feel.
-layout: docs
----
-
-TODO
diff --git a/packages/webawesome/docs/docs/tokens/index.njk b/packages/webawesome/docs/docs/tokens/index.njk
new file mode 100644
index 000000000..1f3141084
--- /dev/null
+++ b/packages/webawesome/docs/docs/tokens/index.njk
@@ -0,0 +1,43 @@
+---
+title: Design Tokens
+description: These custom properties thread through all of Web Awesome's components, giving things a consistent look and feel.
+layout: docs
+override:tags: []
+---
+
+<p>
+{% markdown %}
+  {{ description }}
+{% endmarkdown %}
+</p>
+
+<div class="search-list">
+  <wa-input class="search-list-input" type="search" placeholder="Search design tokens" autofocus>
+    <wa-icon name="search" slot="start"></wa-icon>
+  </wa-input>
+
+  <section class="search-list-grid">
+    {% for page in collections.tokens | sort(false, false, 'data.title') %}
+      <a href="{{ page.url }}">
+        <wa-card with-header="" appearance="outlined">
+          <div slot="header">
+            {# Look for an icon based on the page name #}
+            {% set iconPath = "svgs/tokens/" + page.fileSlug + ".njk" %}
+            {% set iconContent %}{% include iconPath ignore missing %}{% endset %}
+            {% if iconContent.trim() %}
+              {# An icon exists! Show it #}
+              {{ iconContent | safe }}
+            {% else %}
+              {# Fallback to the placeholder #}
+              {% include 'svgs/thumbnail-placeholder.njk' %}
+            {% endif %}
+          </div>
+          <span class="page-name">{{ page.data.title }}</span>
+        </wa-card>
+      </a>
+    {% endfor %}
+  </section>
+  <div class="search-list-empty" hidden>
+    No results found
+  </div>
+</div>
diff --git a/packages/webawesome/docs/docs/tokens/tokens.json b/packages/webawesome/docs/docs/tokens/tokens.json
new file mode 100644
index 000000000..efd54a908
--- /dev/null
+++ b/packages/webawesome/docs/docs/tokens/tokens.json
@@ -0,0 +1,3 @@
+{
+  "tags": ["tokens"]
+}
diff --git a/packages/webawesome/docs/docs/utilities/align-items.md b/packages/webawesome/docs/docs/utilities/align-items.md
index 48f78cd1f..07ce72c73 100644
--- a/packages/webawesome/docs/docs/utilities/align-items.md
+++ b/packages/webawesome/docs/docs/utilities/align-items.md
@@ -2,6 +2,7 @@
 title: Align Items
 description: Align items utilities set the gap property of flex and grid containers, like other Web Awesome layout utilities.
 layout: docs
+tags: layoutUtilities
 ---
 
 <style>
diff --git a/packages/webawesome/docs/docs/utilities/cluster.md b/packages/webawesome/docs/docs/utilities/cluster.md
index 9b52aa8cf..bf3d5ff8a 100644
--- a/packages/webawesome/docs/docs/utilities/cluster.md
+++ b/packages/webawesome/docs/docs/utilities/cluster.md
@@ -2,6 +2,7 @@
 title: Cluster
 description: 'Use the `wa-cluster` class to arrange elements inline with even spacing, allowing items to wrap when space is limited.'
 layout: docs
+tags: layoutUtilities
 ---
 
 <style>
diff --git a/packages/webawesome/docs/docs/utilities/color.md b/packages/webawesome/docs/docs/utilities/color.md
index 71ad3e2c5..c1e1b6fc3 100644
--- a/packages/webawesome/docs/docs/utilities/color.md
+++ b/packages/webawesome/docs/docs/utilities/color.md
@@ -2,6 +2,7 @@
 title: Color Variants
 description: Color utilities allow you to apply the brand, neutral, success, warning, and danger colors from your theme to any element.
 layout: docs
+tags: styleUtilities
 ---
 
 Some Web Awesome components, like `<wa-button>`, allow you to change the color by using a `variant` attribute:
diff --git a/packages/webawesome/docs/docs/utilities/flank.md b/packages/webawesome/docs/docs/utilities/flank.md
index ae03887cc..ded9aa341 100644
--- a/packages/webawesome/docs/docs/utilities/flank.md
+++ b/packages/webawesome/docs/docs/utilities/flank.md
@@ -2,6 +2,7 @@
 title: Flank
 description: 'Use the `wa-flank` class to position two items side-by-side, with one item positioned alongside, or _flanking_, content that stretches to fill the available space.'
 layout: docs
+tags: layoutUtilities
 ---
 
 <style>
diff --git a/packages/webawesome/docs/docs/utilities/fouce.md b/packages/webawesome/docs/docs/utilities/fouce.md
index fa822e187..08a4497c8 100644
--- a/packages/webawesome/docs/docs/utilities/fouce.md
+++ b/packages/webawesome/docs/docs/utilities/fouce.md
@@ -2,6 +2,7 @@
 title: Reducing FOUCE
 description: Utility to improve the loading experience by hiding non-prerendered custom elements until they are registered.
 layout: docs
+tags: styleUtilities
 ---
 
 Often, components are shown before their logic and styles have had a chance to load, also known as a [Flash of Undefined Custom Elements](https://www.abeautifulsite.net/posts/flash-of-undefined-custom-elements/).
diff --git a/packages/webawesome/docs/docs/utilities/frame.md b/packages/webawesome/docs/docs/utilities/frame.md
index 1adc27aab..24e85390d 100644
--- a/packages/webawesome/docs/docs/utilities/frame.md
+++ b/packages/webawesome/docs/docs/utilities/frame.md
@@ -2,6 +2,7 @@
 title: Frame
 description: 'Use the `wa-frame` class to create a responsive container with consistent proportions to enclose content.'
 layout: docs
+tags: layoutUtilities
 ---
 
 <style>
diff --git a/packages/webawesome/docs/docs/utilities/gap.md b/packages/webawesome/docs/docs/utilities/gap.md
index d369535ad..061930786 100644
--- a/packages/webawesome/docs/docs/utilities/gap.md
+++ b/packages/webawesome/docs/docs/utilities/gap.md
@@ -2,6 +2,7 @@
 title: Gap
 description: Gap utilities set the gap property of flex and grid containers, like other Web Awesome layout utilities.
 layout: docs
+tags: layoutUtilities
 ---
 
 <style>
diff --git a/packages/webawesome/docs/docs/utilities/grid.md b/packages/webawesome/docs/docs/utilities/grid.md
index 446023132..35c754bf6 100644
--- a/packages/webawesome/docs/docs/utilities/grid.md
+++ b/packages/webawesome/docs/docs/utilities/grid.md
@@ -2,6 +2,7 @@
 title: Grid
 description: 'Use the `wa-grid` class to arrange elements into rows and columns that automatically adapt to the available space.'
 layout: docs
+tags: layoutUtilities
 ---
 
 <style>
diff --git a/packages/webawesome/docs/docs/utilities/index.md b/packages/webawesome/docs/docs/utilities/index.md
deleted file mode 100644
index 73c85c76b..000000000
--- a/packages/webawesome/docs/docs/utilities/index.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: Style Utilities
-description:
-  Style utilities are preset rules that let you efficiently customize styles for components and native elements alike.
-  See the [installation instructions](#installation) to use style utilities in your project.
-layout: docs
----
-
-## Installation
-
-To use all Web Awesome page styles (including [native styles](/docs/utilities/native/)), include the following stylesheet in your project:
-
-```html
-<link rel="stylesheet" href="{% cdnUrl 'styles/webawesome.css' %}" />
-```
-
-Or, to _only_ include utilities:
-
-```html
-<link rel="stylesheet" href="{% cdnUrl 'styles/utilities.css' %}" />
-```
diff --git a/packages/webawesome/docs/docs/utilities/index.njk b/packages/webawesome/docs/docs/utilities/index.njk
new file mode 100644
index 000000000..0ff7e2ee2
--- /dev/null
+++ b/packages/webawesome/docs/docs/utilities/index.njk
@@ -0,0 +1,66 @@
+---
+title: Style Utilities
+description:
+  Style utilities are preset rules that let you efficiently customize styles for components and native elements alike.
+  See the [installation instructions](#installation) to use style utilities in your project.
+layout: docs
+---
+
+<p>
+{% markdown %}
+  {{ description }}
+{% endmarkdown %}
+</p>
+
+<div class="search-list">
+  <wa-input class="search-list-input" type="search" placeholder="Search style utilities" autofocus>
+    <wa-icon name="search" slot="start"></wa-icon>
+  </wa-input>
+
+  <section class="search-list-grid">
+    {% for page in collections.styleUtilities | sort(false, false, 'data.title') %}
+      <a href="{{ page.url }}">
+        <wa-card with-header="" appearance="outlined">
+          <div slot="header">
+            {# Look for an icon based on the page name #}
+            {% set iconPath = "svgs/tokens/" + page.fileSlug + ".njk" %}
+            {% set iconContent %}{% include iconPath ignore missing %}{% endset %}
+            {% if iconContent.trim() %}
+              {# An icon exists! Show it #}
+              {{ iconContent | safe }}
+            {% else %}
+              {# Fallback to the placeholder #}
+              {% include 'svgs/thumbnail-placeholder.njk' %}
+            {% endif %}
+          </div>
+          <span class="page-name">{{ page.data.title }}</span>
+        </wa-card>
+      </a>
+    {% endfor %}
+  </section>
+  <div class="search-list-empty" hidden>
+    No results found
+  </div>
+</div>
+
+<wa-divider style="--spacing: var(--wa-space-3xl);"></wa-divider>
+
+<div class="max-line-length">
+{% markdown %}
+## Installation
+
+To use all Web Awesome page styles (including [native styles](/docs/utilities/native/)), include the following stylesheet in your project:
+
+```html
+<link rel="stylesheet" href="{% cdnUrl 'styles/webawesome.css' %}" />
+```
+
+Or, to _only_ include utilities:
+
+```html
+<link rel="stylesheet" href="{% cdnUrl 'styles/utilities.css' %}" />
+```
+
+{% endmarkdown %}
+
+</div>
diff --git a/packages/webawesome/docs/docs/utilities/native.md b/packages/webawesome/docs/docs/utilities/native.md
index 8a411c578..b320ceeb2 100644
--- a/packages/webawesome/docs/docs/utilities/native.md
+++ b/packages/webawesome/docs/docs/utilities/native.md
@@ -2,6 +2,7 @@
 title: Native Styles
 description: Native styles apply your theme to native HTML elements so they match the look and feel of Web Awesome components.
 layout: page-outline
+tags: styleUtilities
 ---
 
 Web Awesome provides optional Native Styles that make native HTML elements look good so you can continue using what you know and gradually adopt Web Awesome as you see fit.
diff --git a/packages/webawesome/docs/docs/utilities/rounding.md b/packages/webawesome/docs/docs/utilities/rounding.md
index 78e9c3b76..b0637d501 100644
--- a/packages/webawesome/docs/docs/utilities/rounding.md
+++ b/packages/webawesome/docs/docs/utilities/rounding.md
@@ -2,6 +2,7 @@
 title: Rounding Utilities
 description: Border radius utilities set an element's border radius property.
 layout: docs
+tags: styleUtilities
 ---
 
 <style>
diff --git a/packages/webawesome/docs/docs/utilities/split.md b/packages/webawesome/docs/docs/utilities/split.md
index 9dfb76934..962751ef5 100644
--- a/packages/webawesome/docs/docs/utilities/split.md
+++ b/packages/webawesome/docs/docs/utilities/split.md
@@ -2,6 +2,7 @@
 title: Split
 description: 'Use the `wa-split` class to distribute two or more items evenly across available space, either in a row or a column.'
 layout: docs
+tags: layoutUtilities
 ---
 
 <style>
diff --git a/packages/webawesome/docs/docs/utilities/stack.md b/packages/webawesome/docs/docs/utilities/stack.md
index b89cec4c8..561955807 100644
--- a/packages/webawesome/docs/docs/utilities/stack.md
+++ b/packages/webawesome/docs/docs/utilities/stack.md
@@ -2,6 +2,7 @@
 title: Stack
 description: 'Use `wa-stack` to arrange elements in the block direction with even spacing.'
 layout: docs
+tags: layoutUtilities
 ---
 
 <style>
diff --git a/packages/webawesome/docs/docs/utilities/text.md b/packages/webawesome/docs/docs/utilities/text.md
index c3fc56bf4..35fcdd77e 100644
--- a/packages/webawesome/docs/docs/utilities/text.md
+++ b/packages/webawesome/docs/docs/utilities/text.md
@@ -2,6 +2,7 @@
 title: Text
 description: Text utility classes combine custom properties from your Web Awesome theme to conveniently style text content.
 layout: docs
+tags: styleUtilities
 ---
 
 Web Awesome includes classes to set multiple text properties at once to style body text, headings, and captions.
diff --git a/packages/webawesome/docs/docs/utilities/visually-hidden.md b/packages/webawesome/docs/docs/utilities/visually-hidden.md
index 1147aee0a..23e608548 100644
--- a/packages/webawesome/docs/docs/utilities/visually-hidden.md
+++ b/packages/webawesome/docs/docs/utilities/visually-hidden.md
@@ -2,6 +2,7 @@
 title: Visually Hidden
 description: The visually hidden utility makes content accessible to assistive devices without displaying it on the screen.
 layout: docs
+tags: styleUtilities
 ---
 
 > "There are real world situations where visually hiding content may be appropriate, while the content should remain available to assistive technologies, such as screen readers. For instance, hiding a search field's label as a common magnifying glass icon is used in its stead."