From eb10fad1fcc30a6f405ee2df13a921381266b75b Mon Sep 17 00:00:00 2001
From: Steven Spriggs <steven.spriggs@gmail.com>
Date: Fri, 13 Sep 2024 17:48:25 -0400
Subject: [PATCH] docs: refactor styles and accessibility fixes (#1820)

* docs: refactor styles and accessibility fixes

* docs: remove semantic aside tag
---
 docs/_includes/layouts/pages/basic.njk       |   8 +-
 docs/_includes/layouts/pages/elements.njk    |   8 +-
 docs/_includes/layouts/pages/pattern.njk     |   8 +-
 docs/assets/javascript/elements/uxdot-toc.ts |   8 +-
 docs/styles/pages/backpage.css               | 141 +++++++++----------
 5 files changed, 87 insertions(+), 86 deletions(-)

diff --git a/docs/_includes/layouts/pages/basic.njk b/docs/_includes/layouts/pages/basic.njk
index 1157a4d2df..3258f6ee8e 100755
--- a/docs/_includes/layouts/pages/basic.njk
+++ b/docs/_includes/layouts/pages/basic.njk
@@ -22,9 +22,11 @@ importElements:
 
   {% include 'partials/component/header.njk' %}
   {% if hasToc and (content | toc).length > 0 %}
-  <uxdot-toc summary="On this page">
-    {{ content | toc | safe }}
-  </uxdot-toc>
+  <div class="aside">
+    <uxdot-toc summary="On this page">
+      {{ content | toc | safe }}
+    </uxdot-toc>
+  </div>
   {% endif %}
 
   <div class="container">
diff --git a/docs/_includes/layouts/pages/elements.njk b/docs/_includes/layouts/pages/elements.njk
index 22191a5759..c7ccfc5373 100644
--- a/docs/_includes/layouts/pages/elements.njk
+++ b/docs/_includes/layouts/pages/elements.njk
@@ -69,9 +69,11 @@ eleventyComputed:
     </uxdot-header>
 
     {% if hasToc and (content | toc).length > 0 %}
-    <uxdot-toc summary="On this page">
-      {{ content | toc | safe }}
-    </uxdot-toc>
+    <div class="aside">
+      <uxdot-toc summary="On this page">
+        {{ content | toc | safe }}
+      </uxdot-toc>
+    </div>
     {% endif %}
 
     <div class="container">
diff --git a/docs/_includes/layouts/pages/pattern.njk b/docs/_includes/layouts/pages/pattern.njk
index f3e6e883eb..fc843659be 100755
--- a/docs/_includes/layouts/pages/pattern.njk
+++ b/docs/_includes/layouts/pages/pattern.njk
@@ -23,9 +23,11 @@ importElements:
 
   {% include 'partials/component/header.njk' %}
   {% if hasToc and (content | toc).length > 0 %}
-  <uxdot-toc summary="On this page">
-    {{ content | toc | safe }}
-  </uxdot-toc>
+  <div class="aside">
+    <uxdot-toc summary="On this page">
+      {{ content | toc | safe }}
+    </uxdot-toc>
+  </div>
   {% endif %}
 
   <div class="container">
diff --git a/docs/assets/javascript/elements/uxdot-toc.ts b/docs/assets/javascript/elements/uxdot-toc.ts
index ed58f329dc..e5c54f344e 100644
--- a/docs/assets/javascript/elements/uxdot-toc.ts
+++ b/docs/assets/javascript/elements/uxdot-toc.ts
@@ -13,20 +13,20 @@ export class UxdotToc extends LitElement {
 
   render() {
     return html`
-      <aside id="container" part="container">
+      <div id="container" part="container">
         <details>
           <summary id="summary">${this.summary}</summary>
-          <nav aria-describedby="summary">
+          <nav aria-labelledby="summary">
             <slot name="details"></slot>
           </nav>
         </details>
         <div id="expanded">
           <div id="summary">${this.summary}</div>
-          <nav>
+          <nav aria-labelledby="summary">
             <slot name="expanded"></slot>
           </nav>
         </div>
-      </aside>
+      </div>
     `;
   }
 }
diff --git a/docs/styles/pages/backpage.css b/docs/styles/pages/backpage.css
index d10a1e20c6..e3ecefb30b 100644
--- a/docs/styles/pages/backpage.css
+++ b/docs/styles/pages/backpage.css
@@ -7,23 +7,85 @@
       "header"
       "content";
     row-gap: var(--rh-space-4xl);
-  }
 
-  article.has-toc {
-    grid-template-areas:
-      "header"
-      "aside"
-      "content";
+    &.has-toc {
+      grid-template-areas:
+        "header"
+        "aside"
+        "content";
+    }
+
+    @container main (min-width: 992px) {
+      row-gap: var(--rh-space-6xl);
+    }
+
+    @container main (min-width: 1440px) {
+      grid-template-columns:
+        minmax(
+            var(--container-min-width),
+            var(--container-max-width)
+          )
+        minmax(14rem, 1fr);
+      grid-template-areas:
+        "header header"
+        "content content";
+
+      &.has-toc {
+        grid-template-areas:
+          "header header"
+          "content aside";
+
+        & .aside {
+          height: max-content;
+          max-width: 320px;
+          padding-inline: 0 var(--rh-space-2xl);
+          position: sticky;
+
+          /* masthead height (72px) + padding (32px) */
+          top: calc(var(--uxdot-masthead-max-height) + var(--rh-space-2xl));
+        }
+
+        &:has(uxdot-header[has-subnav]) .aside {
+          /* masthead height (72px) + sub-nav height (56px) + padding (32px) */
+          top: calc(var(--uxdot-masthead-max-height) + 56px + var(--rh-space-2xl));
+        }
+      }
+    }
   }
 
   uxdot-header {
     grid-area: header;
   }
 
+  .aside {
+    grid-area: aside;
+    padding-inline: var(--rh-space-lg);
+
+    @container main (min-width: 576px) {
+      padding-inline: var(--rh-space-2xl);
+    }
+
+    @container main (min-width: 768px) {
+      padding-inline: var(--rh-space-3xl);
+    }
+
+    @container main (min-width: 992px) {
+      padding-inline: var(--rh-space-6xl);
+    }
+  }
+
   .container {
     grid-area: content;
     container-type: inline-size;
     container-name: container;
+
+    & > section {
+      margin-block-start: var(--rh-space-6xl);
+    }
+
+    & > section:first-of-type {
+      margin-block-start: 0;
+    }
   }
 
   .container h2,
@@ -55,20 +117,6 @@
     max-width: 56rem;
   }
 
-  uxdot-toc {
-    grid-area: aside;
-    padding-inline: var(--rh-space-lg);
-  }
-
-  /* when a section is used */
-  .container > section {
-    margin-block-start: var(--rh-space-6xl);
-  }
-
-  .container > section:first-of-type {
-    margin-block-start: 0;
-  }
-
   /*
   when in a article container
   where a h2 or uxdot-copy-permalink is used
@@ -119,57 +167,4 @@
   .container > section > :where(uxdot-copy-permalink.h4, h4) {
     margin-block-start: var(--rh-space-3xl);
   }
-
-  @container main (min-width: 576px) {
-    uxdot-toc {
-      padding-inline: var(--rh-space-2xl);
-    }
-  }
-
-  @container main (min-width: 768px) {
-    uxdot-toc {
-      padding-inline: var(--rh-space-3xl);
-    }
-  }
-
-  @container main (min-width: 992px) {
-    article {
-      row-gap: var(--rh-space-6xl);
-    }
-
-    uxdot-toc {
-      padding-inline: var(--rh-space-6xl);
-    }
-  }
-
-  /* this follows the @media queries so that it can override the aside */
-  @container main (min-width: 1440px) {
-    article {
-      grid-template-columns:
-        minmax(
-            var(--container-min-width),
-            var(--container-max-width)
-          )
-        minmax(14rem, 1fr);
-      grid-template-areas:
-        "header header"
-        "content content";
-    }
-
-    article.has-toc {
-      grid-template-areas:
-        "header header"
-        "content aside";
-
-      & uxdot-toc {
-        padding-inline: 0 var(--rh-space-2xl);
-        max-width: 320px;
-        position: sticky;
-        height: max-content;
-
-        /* masthead height (72px) + padding (32px) */
-        top: calc(var(--uxdot-masthead-max-height) + var(--rh-space-2xl) * 3);
-      }
-    }
-  }
 }