From b4896593e380873ce9c3a42edb3ea044c9b7edf4 Mon Sep 17 00:00:00 2001
From: Leo McArdle <leo@mozilla.com>
Date: Tue, 9 Dec 2025 18:02:02 +0000
Subject: [PATCH 01/12] add --layout-sidebar-padding variable and refactor

add --layout-sidebar-padding variable for padding between sidebar
content and document content, so the scrollbar isn't pushed up against
the content

this removes my ugly hack from before where I set a negative right
margin on the left sidebar

sets --layout-sidebar-padding to 1rem + 2px to make the gap between sidebar
content and document content the same as it currently is

increases --layout-sidebar-min by 1rem so sidebars content doesn't get
any narrower

absorbs the --layout-side-padding-min padding into the left of the left
sidebar to avoid 2px padding for focus outlines and give us greater
flexibility with the sidebar layout in the future

does the same on the right of the right sidebar to align the right
sidebar scrollbar with the right of the screen on smaller displays
---
 components/layout/global.css           | 15 +++++-----
 components/left-sidebar/server.css     |  7 -----
 components/reference-layout/server.css | 41 +++++++++++++++++++-------
 3 files changed, 39 insertions(+), 24 deletions(-)

diff --git a/components/layout/global.css b/components/layout/global.css
index 0ca1286e7..5c2db0d85 100644
--- a/components/layout/global.css
+++ b/components/layout/global.css
@@ -1,9 +1,9 @@
 /* --layout-side-padding-min * 2 + (--layout-sidebar-min + --layout-sidebar-gap) * 2 + --layout-content-min */
-@custom-media --screen-layout-2-sidebars (width >= calc(1rem * 2 + (14rem + 2rem) * 2 + 31rem));
-@custom-media --screen-layout-1-sidebar-or-less (width < calc(1rem * 2 + (14rem + 2rem) * 2 + 31rem));
+@custom-media --screen-layout-2-sidebars (width >= calc(1rem * 2 + (15rem + 1rem) * 2 + 31rem));
+@custom-media --screen-layout-1-sidebar-or-less (width < calc(1rem * 2 + (15rem + 1rem) * 2 + 31rem));
 
 /* --layout-side-padding-min * 2 + --layout-sidebar-min + --layout-sidebar-gap + --layout-content-min */
-@custom-media --screen-layout-no-sidebar (width < calc(1rem * 2 + 14rem + 2rem + 31rem));
+@custom-media --screen-layout-no-sidebar (width < calc(1rem * 2 + 15rem + 1rem + 31rem));
 
 :root {
   --layout-side-padding-min: 1rem;
@@ -13,13 +13,14 @@
   );
   --layout-full-width: calc(100vw - 2 * var(--layout-side-padding));
 
-  --layout-sidebar-min: 14rem;
-  --layout-sidebar-gap: 2rem;
+  --layout-sidebar-min: 15rem;
+  --layout-sidebar-gap: 1rem;
+
+  /* maintain existing gap, will remove/simplify soon: */
+  --layout-sidebar-padding: calc(1rem + 2px);
   --layout-content-min: 31rem;
   --layout-content-max: 48rem;
 
-  /* WARNING: TODO: left/center/right cols widths will change */
-
   /* prettier-ignore */
   --layout-2-sidebars:
     [full-start left-sidebar-start]
diff --git a/components/left-sidebar/server.css b/components/left-sidebar/server.css
index bd8b120c7..d6c17bd53 100644
--- a/components/left-sidebar/server.css
+++ b/components/left-sidebar/server.css
@@ -131,12 +131,6 @@
   }
 }
 
-.left-sidebar__content {
-  > ol {
-    padding-left: 2px;
-  }
-}
-
 .left-sidebar__header {
   position: sticky;
   top: 0;
@@ -145,7 +139,6 @@
   padding-top: 0.5rem;
   padding-right: 0.5rem;
   padding-bottom: 2rem;
-  padding-left: 2px;
 
   background: linear-gradient(
     to bottom,
diff --git a/components/reference-layout/server.css b/components/reference-layout/server.css
index 00c07beea..4fea2b0a2 100644
--- a/components/reference-layout/server.css
+++ b/components/reference-layout/server.css
@@ -37,13 +37,6 @@
 
   .reference-layout__sidebar {
     grid-area: sidebar;
-
-    @media (--screen-layout-2-sidebars) {
-      .left-sidebar {
-        padding-right: calc(var(--layout-sidebar-gap) / 2);
-        margin-right: calc(var(--layout-sidebar-gap) / -2);
-      }
-    }
   }
 
   .reference-layout__toc {
@@ -66,9 +59,23 @@
 
     max-height: calc(100vh - var(--sticky-header-height));
 
-    padding-left: 2px;
-
     overflow-y: auto;
+
+    outline-offset: -2px;
+  }
+
+  @media (--screen-layout-2-sidebars) {
+    .reference-layout__sidebar .left-sidebar {
+      padding-right: var(--layout-sidebar-padding);
+      padding-left: var(--layout-side-padding-min);
+      margin-left: calc(-1 * var(--layout-side-padding-min));
+    }
+
+    .reference-layout__toc {
+      padding-right: var(--layout-side-padding-min);
+      padding-left: var(--layout-sidebar-padding);
+      margin-right: calc(-1 * var(--layout-side-padding-min));
+    }
   }
 
   @media (--screen-layout-1-sidebar-or-less) {
@@ -86,11 +93,25 @@
 
       background: var(--color-background-page);
     }
+
+    .reference-layout__sidebar .left-sidebar,
+    .reference-layout__toc {
+      padding-right: var(--layout-sidebar-padding);
+      padding-left: var(--layout-side-padding-min);
+      margin-left: calc(-1 * var(--layout-side-padding-min));
+    }
   }
 
   @media (--screen-layout-no-sidebar) {
     display: block;
 
+    .reference-layout__sidebar .left-sidebar,
+    .reference-layout__toc {
+      padding-right: unset;
+      padding-left: unset;
+      margin-left: unset;
+    }
+
     .reference-layout__sidebar {
       position: fixed;
       inset: 0;
@@ -98,7 +119,7 @@
       z-index: var(--z-index-sidebar-mobile);
 
       .left-sidebar {
-        padding: 0 1rem;
+        padding: 0 var(--layout-side-padding-min);
       }
     }
 

From 43eb0d9f7692d8fd950abaf9d8396dbff49abac7 Mon Sep 17 00:00:00 2001
From: Leo McArdle <leo@mozilla.com>
Date: Tue, 9 Dec 2025 18:35:38 +0000
Subject: [PATCH 02/12] don't set layout styles on .left-sidebar

move them up to .reference-layout__sidebar
---
 components/left-sidebar/server.css     |  4 ----
 components/reference-layout/server.css | 12 +++++-------
 2 files changed, 5 insertions(+), 11 deletions(-)

diff --git a/components/left-sidebar/server.css b/components/left-sidebar/server.css
index d6c17bd53..a78263ac7 100644
--- a/components/left-sidebar/server.css
+++ b/components/left-sidebar/server.css
@@ -1,9 +1,5 @@
 .left-sidebar {
-  position: sticky;
-  top: var(--sticky-header-height);
-
   padding-bottom: 3rem;
-
   overflow-wrap: anywhere;
 
   h4 {
diff --git a/components/reference-layout/server.css b/components/reference-layout/server.css
index 4fea2b0a2..57f82f784 100644
--- a/components/reference-layout/server.css
+++ b/components/reference-layout/server.css
@@ -52,7 +52,7 @@
     justify-content: space-between;
   }
 
-  .reference-layout__sidebar .left-sidebar,
+  .reference-layout__sidebar,
   .reference-layout__toc {
     position: sticky;
     top: var(--sticky-header-height);
@@ -65,7 +65,7 @@
   }
 
   @media (--screen-layout-2-sidebars) {
-    .reference-layout__sidebar .left-sidebar {
+    .reference-layout__sidebar {
       padding-right: var(--layout-sidebar-padding);
       padding-left: var(--layout-side-padding-min);
       margin-left: calc(-1 * var(--layout-side-padding-min));
@@ -94,7 +94,7 @@
       background: var(--color-background-page);
     }
 
-    .reference-layout__sidebar .left-sidebar,
+    .reference-layout__sidebar,
     .reference-layout__toc {
       padding-right: var(--layout-sidebar-padding);
       padding-left: var(--layout-side-padding-min);
@@ -105,7 +105,7 @@
   @media (--screen-layout-no-sidebar) {
     display: block;
 
-    .reference-layout__sidebar .left-sidebar,
+    .reference-layout__sidebar,
     .reference-layout__toc {
       padding-right: unset;
       padding-left: unset;
@@ -118,9 +118,7 @@
       top: var(--sticky-header-height);
       z-index: var(--z-index-sidebar-mobile);
 
-      .left-sidebar {
-        padding: 0 var(--layout-side-padding-min);
-      }
+      padding: 0 var(--layout-side-padding-min);
     }
 
     .reference-layout__toc {

From 86c3cd674340c06bf07c64512144c3bc3a32751a Mon Sep 17 00:00:00 2001
From: Leo McArdle <leo@mozilla.com>
Date: Tue, 9 Dec 2025 18:42:45 +0000
Subject: [PATCH 03/12] duplicate reference-layout to layout/2-sidebars

---
 components/layout/2-sidebars.css | 138 +++++++++++++++++++++++++++++++
 1 file changed, 138 insertions(+)
 create mode 100644 components/layout/2-sidebars.css

diff --git a/components/layout/2-sidebars.css b/components/layout/2-sidebars.css
new file mode 100644
index 000000000..57f82f784
--- /dev/null
+++ b/components/layout/2-sidebars.css
@@ -0,0 +1,138 @@
+/* Reference Layout */
+
+.reference-layout {
+  display: grid;
+
+  grid-template-areas:
+    "sidebar . header . toc"
+    "sidebar . body   . toc";
+  grid-template-rows: min-content 1fr;
+  grid-template-columns: var(--layout-2-sidebars);
+
+  justify-content: space-between;
+
+  padding-inline: var(--layout-side-padding);
+
+  .reference-layout__content {
+    display: contents;
+  }
+
+  .reference-layout__header {
+    grid-area: header;
+
+    h1 {
+      margin: 1rem 0;
+
+      font-size: var(--font-size-largest);
+      font-weight: normal;
+
+      line-height: var(--font-line-normal);
+    }
+  }
+
+  .reference-layout__body {
+    grid-area: body;
+    padding-bottom: 3rem;
+  }
+
+  .reference-layout__sidebar {
+    grid-area: sidebar;
+  }
+
+  .reference-layout__toc {
+    display: flex;
+
+    flex-wrap: wrap;
+
+    grid-area: toc;
+
+    gap: 0.5rem;
+    align-content: start;
+    align-items: start;
+    justify-content: space-between;
+  }
+
+  .reference-layout__sidebar,
+  .reference-layout__toc {
+    position: sticky;
+    top: var(--sticky-header-height);
+
+    max-height: calc(100vh - var(--sticky-header-height));
+
+    overflow-y: auto;
+
+    outline-offset: -2px;
+  }
+
+  @media (--screen-layout-2-sidebars) {
+    .reference-layout__sidebar {
+      padding-right: var(--layout-sidebar-padding);
+      padding-left: var(--layout-side-padding-min);
+      margin-left: calc(-1 * var(--layout-side-padding-min));
+    }
+
+    .reference-layout__toc {
+      padding-right: var(--layout-side-padding-min);
+      padding-left: var(--layout-sidebar-padding);
+      margin-right: calc(-1 * var(--layout-side-padding-min));
+    }
+  }
+
+  @media (--screen-layout-1-sidebar-or-less) {
+    grid-template-areas:
+      "toc . header"
+      "toc . body";
+    grid-template-columns: var(--layout-1-sidebar-left);
+
+    .reference-layout__sidebar {
+      z-index: 1;
+
+      display: none;
+
+      grid-area: toc;
+
+      background: var(--color-background-page);
+    }
+
+    .reference-layout__sidebar,
+    .reference-layout__toc {
+      padding-right: var(--layout-sidebar-padding);
+      padding-left: var(--layout-side-padding-min);
+      margin-left: calc(-1 * var(--layout-side-padding-min));
+    }
+  }
+
+  @media (--screen-layout-no-sidebar) {
+    display: block;
+
+    .reference-layout__sidebar,
+    .reference-layout__toc {
+      padding-right: unset;
+      padding-left: unset;
+      margin-left: unset;
+    }
+
+    .reference-layout__sidebar {
+      position: fixed;
+      inset: 0;
+      top: var(--sticky-header-height);
+      z-index: var(--z-index-sidebar-mobile);
+
+      padding: 0 var(--layout-side-padding-min);
+    }
+
+    .reference-layout__toc {
+      position: unset;
+      top: unset;
+
+      max-height: unset;
+
+      overflow-y: unset;
+      --toc-header-font-size: var(--font-size-larger);
+    }
+  }
+
+  mdn-survey {
+    margin-top: 0.5rem;
+  }
+}

From 1c2c6c13ed942e6dfb801ec5a4483c69a4b21f92 Mon Sep 17 00:00:00 2001
From: Leo McArdle <leo@mozilla.com>
Date: Tue, 9 Dec 2025 18:45:01 +0000
Subject: [PATCH 04/12] remove layout stuff from reference-layout and
 reference-layout stuff from 2-sidebars

committed with --no-verify to make diffs almost inverse of each other
---
 components/layout/2-sidebars.css       |  26 -------
 components/reference-layout/server.css | 101 +------------------------
 2 files changed, 2 insertions(+), 125 deletions(-)

diff --git a/components/layout/2-sidebars.css b/components/layout/2-sidebars.css
index 57f82f784..1718915e6 100644
--- a/components/layout/2-sidebars.css
+++ b/components/layout/2-sidebars.css
@@ -1,5 +1,3 @@
-/* Reference Layout */
-
 .reference-layout {
   display: grid;
 
@@ -19,20 +17,10 @@
 
   .reference-layout__header {
     grid-area: header;
-
-    h1 {
-      margin: 1rem 0;
-
-      font-size: var(--font-size-largest);
-      font-weight: normal;
-
-      line-height: var(--font-line-normal);
-    }
   }
 
   .reference-layout__body {
     grid-area: body;
-    padding-bottom: 3rem;
   }
 
   .reference-layout__sidebar {
@@ -40,16 +28,7 @@
   }
 
   .reference-layout__toc {
-    display: flex;
-
-    flex-wrap: wrap;
-
     grid-area: toc;
-
-    gap: 0.5rem;
-    align-content: start;
-    align-items: start;
-    justify-content: space-between;
   }
 
   .reference-layout__sidebar,
@@ -128,11 +107,6 @@
       max-height: unset;
 
       overflow-y: unset;
-      --toc-header-font-size: var(--font-size-larger);
     }
   }
-
-  mdn-survey {
-    margin-top: 0.5rem;
-  }
 }
diff --git a/components/reference-layout/server.css b/components/reference-layout/server.css
index 57f82f784..e0694f725 100644
--- a/components/reference-layout/server.css
+++ b/components/reference-layout/server.css
@@ -1,25 +1,9 @@
+@import url("../layout/2-sidebars.css");
+
 /* Reference Layout */
 
 .reference-layout {
-  display: grid;
-
-  grid-template-areas:
-    "sidebar . header . toc"
-    "sidebar . body   . toc";
-  grid-template-rows: min-content 1fr;
-  grid-template-columns: var(--layout-2-sidebars);
-
-  justify-content: space-between;
-
-  padding-inline: var(--layout-side-padding);
-
-  .reference-layout__content {
-    display: contents;
-  }
-
   .reference-layout__header {
-    grid-area: header;
-
     h1 {
       margin: 1rem 0;
 
@@ -31,103 +15,22 @@
   }
 
   .reference-layout__body {
-    grid-area: body;
     padding-bottom: 3rem;
   }
 
-  .reference-layout__sidebar {
-    grid-area: sidebar;
-  }
-
   .reference-layout__toc {
     display: flex;
 
     flex-wrap: wrap;
 
-    grid-area: toc;
-
     gap: 0.5rem;
     align-content: start;
     align-items: start;
     justify-content: space-between;
   }
 
-  .reference-layout__sidebar,
-  .reference-layout__toc {
-    position: sticky;
-    top: var(--sticky-header-height);
-
-    max-height: calc(100vh - var(--sticky-header-height));
-
-    overflow-y: auto;
-
-    outline-offset: -2px;
-  }
-
-  @media (--screen-layout-2-sidebars) {
-    .reference-layout__sidebar {
-      padding-right: var(--layout-sidebar-padding);
-      padding-left: var(--layout-side-padding-min);
-      margin-left: calc(-1 * var(--layout-side-padding-min));
-    }
-
-    .reference-layout__toc {
-      padding-right: var(--layout-side-padding-min);
-      padding-left: var(--layout-sidebar-padding);
-      margin-right: calc(-1 * var(--layout-side-padding-min));
-    }
-  }
-
-  @media (--screen-layout-1-sidebar-or-less) {
-    grid-template-areas:
-      "toc . header"
-      "toc . body";
-    grid-template-columns: var(--layout-1-sidebar-left);
-
-    .reference-layout__sidebar {
-      z-index: 1;
-
-      display: none;
-
-      grid-area: toc;
-
-      background: var(--color-background-page);
-    }
-
-    .reference-layout__sidebar,
-    .reference-layout__toc {
-      padding-right: var(--layout-sidebar-padding);
-      padding-left: var(--layout-side-padding-min);
-      margin-left: calc(-1 * var(--layout-side-padding-min));
-    }
-  }
-
   @media (--screen-layout-no-sidebar) {
-    display: block;
-
-    .reference-layout__sidebar,
-    .reference-layout__toc {
-      padding-right: unset;
-      padding-left: unset;
-      margin-left: unset;
-    }
-
-    .reference-layout__sidebar {
-      position: fixed;
-      inset: 0;
-      top: var(--sticky-header-height);
-      z-index: var(--z-index-sidebar-mobile);
-
-      padding: 0 var(--layout-side-padding-min);
-    }
-
     .reference-layout__toc {
-      position: unset;
-      top: unset;
-
-      max-height: unset;
-
-      overflow-y: unset;
       --toc-header-font-size: var(--font-size-larger);
     }
   }

From 1827cbce047616e570f797dcacb6e0bfdc4d8a55 Mon Sep 17 00:00:00 2001
From: Leo McArdle <leo@mozilla.com>
Date: Tue, 9 Dec 2025 18:54:26 +0000
Subject: [PATCH 05/12] make names more generic in 2-sidebars and apply to
 reference-layout

---
 components/layout/2-sidebars.css      | 52 +++++++++++++--------------
 components/reference-layout/server.js | 15 ++++----
 2 files changed, 34 insertions(+), 33 deletions(-)

diff --git a/components/layout/2-sidebars.css b/components/layout/2-sidebars.css
index 1718915e6..3f3eeb673 100644
--- a/components/layout/2-sidebars.css
+++ b/components/layout/2-sidebars.css
@@ -1,9 +1,9 @@
-.reference-layout {
+.layout__2-sidebars {
   display: grid;
 
   grid-template-areas:
-    "sidebar . header . toc"
-    "sidebar . body   . toc";
+    "left-sidebar . header . right-sidebar"
+    "left-sidebar . body   . right-sidebar";
   grid-template-rows: min-content 1fr;
   grid-template-columns: var(--layout-2-sidebars);
 
@@ -11,28 +11,28 @@
 
   padding-inline: var(--layout-side-padding);
 
-  .reference-layout__content {
+  .layout__content {
     display: contents;
   }
 
-  .reference-layout__header {
+  .layout__header {
     grid-area: header;
   }
 
-  .reference-layout__body {
+  .layout__body {
     grid-area: body;
   }
 
-  .reference-layout__sidebar {
-    grid-area: sidebar;
+  .layout__left-sidebar {
+    grid-area: left-sidebar;
   }
 
-  .reference-layout__toc {
-    grid-area: toc;
+  .layout__right-sidebar {
+    grid-area: right-sidebar;
   }
 
-  .reference-layout__sidebar,
-  .reference-layout__toc {
+  .layout__left-sidebar,
+  .layout__right-sidebar {
     position: sticky;
     top: var(--sticky-header-height);
 
@@ -44,13 +44,13 @@
   }
 
   @media (--screen-layout-2-sidebars) {
-    .reference-layout__sidebar {
+    .layout__left-sidebar {
       padding-right: var(--layout-sidebar-padding);
       padding-left: var(--layout-side-padding-min);
       margin-left: calc(-1 * var(--layout-side-padding-min));
     }
 
-    .reference-layout__toc {
+    .layout__right-sidebar {
       padding-right: var(--layout-side-padding-min);
       padding-left: var(--layout-sidebar-padding);
       margin-right: calc(-1 * var(--layout-side-padding-min));
@@ -59,22 +59,20 @@
 
   @media (--screen-layout-1-sidebar-or-less) {
     grid-template-areas:
-      "toc . header"
-      "toc . body";
+      "sidebar . header"
+      "sidebar . body";
     grid-template-columns: var(--layout-1-sidebar-left);
 
-    .reference-layout__sidebar {
+    .layout__left-sidebar {
       z-index: 1;
-
       display: none;
-
-      grid-area: toc;
-
       background: var(--color-background-page);
     }
 
-    .reference-layout__sidebar,
-    .reference-layout__toc {
+    .layout__left-sidebar,
+    .layout__right-sidebar {
+      grid-area: sidebar;
+
       padding-right: var(--layout-sidebar-padding);
       padding-left: var(--layout-side-padding-min);
       margin-left: calc(-1 * var(--layout-side-padding-min));
@@ -84,14 +82,14 @@
   @media (--screen-layout-no-sidebar) {
     display: block;
 
-    .reference-layout__sidebar,
-    .reference-layout__toc {
+    .layout__left-sidebar,
+    .layout__right-sidebar {
       padding-right: unset;
       padding-left: unset;
       margin-left: unset;
     }
 
-    .reference-layout__sidebar {
+    .layout__left-sidebar {
       position: fixed;
       inset: 0;
       top: var(--sticky-header-height);
@@ -100,7 +98,7 @@
       padding: 0 var(--layout-side-padding-min);
     }
 
-    .reference-layout__toc {
+    .layout__right-sidebar {
       position: unset;
       top: unset;
 
diff --git a/components/reference-layout/server.js b/components/reference-layout/server.js
index c4803928f..0aab116c1 100644
--- a/components/reference-layout/server.js
+++ b/components/reference-layout/server.js
@@ -21,24 +21,27 @@ export class ReferenceLayout extends ServerComponent {
       doc.body?.map((section) => ContentSection.render(context, section)) || [];
 
     return html`
-      <div class="reference-layout">
-        <main id="content" class="reference-layout__content">
-          <div class="reference-layout__header">
+      <div class="layout__2-sidebars reference-layout">
+        <main id="content" class="layout__content reference-layout__content">
+          <div class="layout__header reference-layout__header">
             ${WRITER_MODE ? WriterToolbar.render(context) : nothing}
             ${TranslationBanner.render(context)}
             <mdn-survey></mdn-survey>
             <h1>${doc.title}</h1>
             ${BaselineIndicator.render(context)} ${description}
           </div>
-          <aside class="reference-layout__toc">
+          <aside class="layout__right-sidebar reference-layout__toc">
             ${ReferenceToc.render(context)}
             <mdn-placement-sidebar></mdn-placement-sidebar>
           </aside>
-          <div class="reference-layout__body">
+          <div class="layout__body reference-layout__body">
             ${sections} ${ArticleFooter.render(context)}
           </div>
         </main>
-        <aside class="reference-layout__sidebar" id="main-sidebar">
+        <aside
+          class="layout__left-sidebar reference-layout__sidebar"
+          id="main-sidebar"
+        >
           ${LeftSidebar.render(context)}
         </aside>
       </div>

From 2c79206de71966e04179b5cb6d01751d68ff53ec Mon Sep 17 00:00:00 2001
From: Leo McArdle <leo@mozilla.com>
Date: Tue, 9 Dec 2025 19:02:00 +0000
Subject: [PATCH 06/12] remove unused `reference-layout__*` classes

---
 components/print/global.css           | 4 ++--
 components/reference-layout/server.js | 7 ++-----
 2 files changed, 4 insertions(+), 7 deletions(-)

diff --git a/components/print/global.css b/components/print/global.css
index af987ac3d..174b6c33f 100644
--- a/components/print/global.css
+++ b/components/print/global.css
@@ -42,8 +42,8 @@
   }
 
   .page-layout__banner,
-  .reference-layout__toc,
-  .reference-layout__sidebar,
+  .layout__left-sidebar,
+  .layout__right-sidebar,
   .footer__socials,
   .footer__links,
   .footer__mozilla,
diff --git a/components/reference-layout/server.js b/components/reference-layout/server.js
index 0aab116c1..4a1965672 100644
--- a/components/reference-layout/server.js
+++ b/components/reference-layout/server.js
@@ -22,7 +22,7 @@ export class ReferenceLayout extends ServerComponent {
 
     return html`
       <div class="layout__2-sidebars reference-layout">
-        <main id="content" class="layout__content reference-layout__content">
+        <main id="content" class="layout__content">
           <div class="layout__header reference-layout__header">
             ${WRITER_MODE ? WriterToolbar.render(context) : nothing}
             ${TranslationBanner.render(context)}
@@ -38,10 +38,7 @@ export class ReferenceLayout extends ServerComponent {
             ${sections} ${ArticleFooter.render(context)}
           </div>
         </main>
-        <aside
-          class="layout__left-sidebar reference-layout__sidebar"
-          id="main-sidebar"
-        >
+        <aside class="layout__left-sidebar" id="main-sidebar">
           ${LeftSidebar.render(context)}
         </aside>
       </div>

From 3d8dce265742487bf05fad0d31c1f5c32ded9a3f Mon Sep 17 00:00:00 2001
From: Leo McArdle <leo@mozilla.com>
Date: Wed, 10 Dec 2025 12:27:26 +0000
Subject: [PATCH 07/12] split 2-sidebars into two classes

.layout__2-sidebars for when the right sidebar is to be hidden on mobile

.layout__2-sidebars-inline for when the right sidebar is to be put
between content header and body on mobile
---
 components/layout/2-sidebars.css      | 71 +++++++++++++++++++--------
 components/reference-layout/server.js |  2 +-
 2 files changed, 52 insertions(+), 21 deletions(-)

diff --git a/components/layout/2-sidebars.css b/components/layout/2-sidebars.css
index 3f3eeb673..2aeae970f 100644
--- a/components/layout/2-sidebars.css
+++ b/components/layout/2-sidebars.css
@@ -1,28 +1,13 @@
-.layout__2-sidebars {
+.layout__2-sidebars,
+.layout__2-sidebars-inline {
   display: grid;
 
-  grid-template-areas:
-    "left-sidebar . header . right-sidebar"
-    "left-sidebar . body   . right-sidebar";
-  grid-template-rows: min-content 1fr;
   grid-template-columns: var(--layout-2-sidebars);
 
   justify-content: space-between;
 
   padding-inline: var(--layout-side-padding);
 
-  .layout__content {
-    display: contents;
-  }
-
-  .layout__header {
-    grid-area: header;
-  }
-
-  .layout__body {
-    grid-area: body;
-  }
-
   .layout__left-sidebar {
     grid-area: left-sidebar;
   }
@@ -58,9 +43,6 @@
   }
 
   @media (--screen-layout-1-sidebar-or-less) {
-    grid-template-areas:
-      "sidebar . header"
-      "sidebar . body";
     grid-template-columns: var(--layout-1-sidebar-left);
 
     .layout__left-sidebar {
@@ -108,3 +90,52 @@
     }
   }
 }
+
+.layout__2-sidebars {
+  .layout__content {
+    grid-area: content;
+  }
+
+  @media (--screen-layout-no-sidebar) {
+    .layout__right-sidebar {
+      display: none;
+    }
+  }
+}
+
+.layout__2-sidebars-inline {
+  grid-template-areas:
+    "left-sidebar . header . right-sidebar"
+    "left-sidebar . body   . right-sidebar";
+  grid-template-rows: min-content 1fr;
+
+  .layout__content {
+    display: contents;
+  }
+
+  .layout__header {
+    grid-area: header;
+  }
+
+  .layout__body {
+    grid-area: body;
+  }
+
+  @media (--screen-layout-1-sidebar-or-less) {
+    grid-template-areas:
+      "sidebar . header"
+      "sidebar . body";
+    grid-template-columns: var(--layout-1-sidebar-left);
+  }
+
+  @media (--screen-layout-no-sidebar) {
+    .layout__right-sidebar {
+      position: unset;
+      top: unset;
+
+      max-height: unset;
+
+      overflow-y: unset;
+    }
+  }
+}
diff --git a/components/reference-layout/server.js b/components/reference-layout/server.js
index 4a1965672..16267824e 100644
--- a/components/reference-layout/server.js
+++ b/components/reference-layout/server.js
@@ -21,7 +21,7 @@ export class ReferenceLayout extends ServerComponent {
       doc.body?.map((section) => ContentSection.render(context, section)) || [];
 
     return html`
-      <div class="layout__2-sidebars reference-layout">
+      <div class="layout__2-sidebars-inline reference-layout">
         <main id="content" class="layout__content">
           <div class="layout__header reference-layout__header">
             ${WRITER_MODE ? WriterToolbar.render(context) : nothing}

From e63640c5df0076f9d16ecbd7126fd42557009fbb Mon Sep 17 00:00:00 2001
From: Leo McArdle <leo@mozilla.com>
Date: Wed, 10 Dec 2025 12:30:50 +0000
Subject: [PATCH 08/12] use layout__2-sidebars in generic-layout

---
 components/generic-layout/server.css  | 61 +++------------------------
 components/generic-layout/server.js   | 13 ++++--
 components/generic-sidebar/server.css |  2 -
 components/generic-toc/server.css     |  3 --
 4 files changed, 14 insertions(+), 65 deletions(-)

diff --git a/components/generic-layout/server.css b/components/generic-layout/server.css
index cbe693b28..71a34fe07 100644
--- a/components/generic-layout/server.css
+++ b/components/generic-layout/server.css
@@ -1,69 +1,18 @@
-/* Generic Layout */
-.generic-layout {
-  display: grid;
-
-  grid-template-areas: "sidebar . body . toc";
-  grid-template-columns: var(--layout-2-sidebars);
-
-  padding-inline: var(--layout-side-padding);
-
-  @media (--screen-layout-1-sidebar-or-less) {
-    grid-template-areas: "leftsidebar . body";
-    grid-template-columns: var(--layout-1-sidebar-left);
-
-    .generic-layout__toc {
-      grid-area: leftsidebar;
-    }
-
-    .generic-layout__sidebar {
-      z-index: 1;
-
-      display: none;
-
-      grid-area: leftsidebar;
+@import url("../layout/2-sidebars.css");
 
-      background: var(--color-background-page);
-    }
-  }
-
-  @media (--screen-layout-no-sidebar) {
-    grid-template-areas: ". body .";
-    grid-template-columns: var(--layout-no-sidebar);
-
-    .generic-layout__toc {
-      display: none;
-    }
-
-    .generic-layout__sidebar {
-      inset: 0;
-      top: var(--sticky-header-height);
-      z-index: var(--z-index-sidebar-mobile);
-
-      display: none;
-
-      grid-area: body;
-
-      .left-sidebar {
-        padding: 1rem;
-      }
-    }
-  }
-}
+/* Generic Layout */
 
 /* Sidebar */
 .generic-layout__sidebar {
-  grid-area: sidebar;
-  padding: 2rem 0;
+  padding-block: 2rem;
 }
 
 /* Content */
 .generic-layout__content {
-  grid-area: body;
-  padding: 2rem 0;
+  padding-block: 2rem;
 }
 
 /* TOC */
 .generic-layout__toc {
-  grid-column: toc;
-  padding: 2rem 0;
+  padding-block: 2rem;
 }
diff --git a/components/generic-layout/server.js b/components/generic-layout/server.js
index d3b097a81..c01e2fdf5 100644
--- a/components/generic-layout/server.js
+++ b/components/generic-layout/server.js
@@ -11,12 +11,17 @@ export class GenericLayout extends ServerComponent {
    */
   render(context) {
     return html`
-      <div class="generic-layout">
-        <aside class="generic-layout__toc">${GenericToc.render(context)}</aside>
-        <div class="generic-layout__content">
+      <div class="layout__2-sidebars generic-layout">
+        <aside class="layout__right-sidebar generic-layout__toc">
+          ${GenericToc.render(context)}
+        </aside>
+        <div class="layout__content generic-layout__content">
           ${GenericContent.render(context)}
         </div>
-        <aside class="generic-layout__sidebar" id="main-sidebar">
+        <aside
+          class="layout__left-sidebar generic-layout__sidebar"
+          id="main-sidebar"
+        >
           ${GenericSidebar.render(context)}
         </aside>
       </div>
diff --git a/components/generic-sidebar/server.css b/components/generic-sidebar/server.css
index aaad83635..19fc1605d 100644
--- a/components/generic-sidebar/server.css
+++ b/components/generic-sidebar/server.css
@@ -3,8 +3,6 @@
   --color-background-accent: var(--color-background-blue);
   --color-border-items: light-dark(var(--color-gray-80), var(--color-gray-20));
 
-  position: sticky;
-  top: var(--sticky-header-height);
   margin-bottom: 2rem;
 
   .generic-sidebar__header {
diff --git a/components/generic-toc/server.css b/components/generic-toc/server.css
index 16a880e7b..9fd2f27b5 100644
--- a/components/generic-toc/server.css
+++ b/components/generic-toc/server.css
@@ -1,7 +1,4 @@
 .generic-toc {
-  position: sticky;
-  top: var(--sticky-header-height);
-
   .generic-toc__header {
     margin: 0 0 1rem;
 

From fe523812cc1e5e6633a69f804da75f7982c529a8 Mon Sep 17 00:00:00 2001
From: Leo McArdle <leo@mozilla.com>
Date: Wed, 10 Dec 2025 12:36:46 +0000
Subject: [PATCH 09/12] hide top banner when content is in single column mode

otherwise we can't consistently position the overlayed sidebar: scroll
to top of page, resize page width to 790px and toggle sidebar to repro

keeping both media queries because --screen-layout-no-sidebar may change
to be smaller than --screen-small-and-narrower in the future again (we
don't want to have to go update other files as we change our min content
and sidebar sizes and paddings)
---
 components/page-layout/server.css | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/components/page-layout/server.css b/components/page-layout/server.css
index 26175eb93..c12c80442 100644
--- a/components/page-layout/server.css
+++ b/components/page-layout/server.css
@@ -29,7 +29,7 @@
     color-scheme: dark;
   }
 
-  @media (--screen-small-and-narrower) {
+  @media (--screen-small-and-narrower) or (--screen-layout-no-sidebar) {
     display: none;
   }
 }

From 5d10a902fb8227825f54d21174ee83ec074d9f6e Mon Sep 17 00:00:00 2001
From: Leo McArdle <leo@mozilla.com>
Date: Wed, 10 Dec 2025 14:22:00 +0000
Subject: [PATCH 10/12] use layout__2-sidebars-inline across curriculum

urls for testing each renderer:
CurriculumAbout: http://localhost:3000/en-US/curriculum/about-curriculum/
CurriculumDefault: http://localhost:3000/en-US/curriculum/faq/
CurriculumModule: http://localhost:3000/en-US/curriculum/getting-started/soft-skills/
CurriculumOverview: http://localhost:3000/en-US/curriculum/getting-started/
---
 components/curriculum-about/server.js    | 21 +++++--
 components/curriculum-default/server.js  | 21 +++++--
 components/curriculum-module/server.js   | 21 +++++--
 components/curriculum-overview/server.js | 51 +++++----------
 components/curriculum/layout.css         | 79 +-----------------------
 components/curriculum/sidebar.css        |  4 --
 components/curriculum/toc.css            |  4 +-
 7 files changed, 63 insertions(+), 138 deletions(-)

diff --git a/components/curriculum-about/server.js b/components/curriculum-about/server.js
index b3e537d70..16921d83e 100644
--- a/components/curriculum-about/server.js
+++ b/components/curriculum-about/server.js
@@ -29,24 +29,33 @@ export class CurriculumAbout extends ServerComponent {
     return PageLayout.render(
       context,
       html`
-        <div class="curriculum-layout curriculum-content-container">
+        <div
+          class="layout__2-sidebars-inline curriculum-layout curriculum-content-container"
+        >
           <main
             id="content"
-            class="curriculum-layout__content curriculum-content-container curriculum-about curriculum-module topic-${topicCssClass}"
+            class="layout__content curriculum-layout__content curriculum-content-container curriculum-about curriculum-module topic-${topicCssClass}"
             lang=${doc.locale}
           >
-            <header class="curriculum-layout__header curriculum-content">
+            <header
+              class="layout__header curriculum-layout__header curriculum-content"
+            >
               <h1><span>${coloredTitle}</span> ${restTitle.join(" ")}</h1>
             </header>
-            <aside class="curriculum-layout__toc">
+            <aside class="layout__right-sidebar curriculum-layout__toc">
               ${toc}
               <mdn-placement-sidebar></mdn-placement-sidebar>
             </aside>
-            <div class="curriculum-layout__body curriculum-content">
+            <div
+              class="layout__body curriculum-layout__body curriculum-content"
+            >
               ${renderCurriculumBody(context, doc)}
             </div>
           </main>
-          <aside class="curriculum-layout__sidebar" id="main-sidebar">
+          <aside
+            class="layout__left-sidebar curriculum-layout__sidebar"
+            id="main-sidebar"
+          >
             ${sidebar}
           </aside>
         </div>
diff --git a/components/curriculum-default/server.js b/components/curriculum-default/server.js
index 218a30ea7..c0fa72113 100644
--- a/components/curriculum-default/server.js
+++ b/components/curriculum-default/server.js
@@ -29,24 +29,33 @@ export class CurriculumDefault extends ServerComponent {
     return PageLayout.render(
       context,
       html`
-        <div class="curriculum-layout curriculum-content-container">
+        <div
+          class="layout__2-sidebars-inline curriculum-layout curriculum-content-container"
+        >
           <main
             id="content"
-            class="curriculum-layout__content curriculum-content-container curriculum-default curriculum-about curriculum-module topic-${topicCssClass}"
+            class="layout__content curriculum-layout__content curriculum-content-container curriculum-default curriculum-about curriculum-module topic-${topicCssClass}"
             lang=${doc.locale}
           >
-            <header class="curriculum-layout__header curriculum-content">
+            <header
+              class="layout__header curriculum-layout__header curriculum-content"
+            >
               <h1><span>${coloredTitle}</span> ${restTitle.join(" ")}</h1>
             </header>
-            <aside class="curriculum-layout__toc">
+            <aside class="layout__right-sidebar curriculum-layout__toc">
               ${toc}
               <mdn-placement-sidebar></mdn-placement-sidebar>
             </aside>
-            <div class="curriculum-layout__body curriculum-content">
+            <div
+              class="layout__body curriculum-layout__body curriculum-content"
+            >
               ${renderCurriculumBody(context, doc)}
             </div>
           </main>
-          <aside class="curriculum-layout__sidebar" id="main-sidebar">
+          <aside
+            class="layout__left-sidebar curriculum-layout__sidebar"
+            id="main-sidebar"
+          >
             ${sidebar}
           </aside>
         </div>
diff --git a/components/curriculum-module/server.js b/components/curriculum-module/server.js
index a7f32100d..4a527d332 100644
--- a/components/curriculum-module/server.js
+++ b/components/curriculum-module/server.js
@@ -32,13 +32,17 @@ export class CurriculumModule extends ServerComponent {
     return PageLayout.render(
       context,
       html`
-        <div class="curriculum-layout curriculum-content-container">
+        <div
+          class="layout__2-sidebars-inline curriculum-layout curriculum-content-container"
+        >
           <main
             id="content"
-            class="curriculum-layout__content curriculum-content-container curriculum-module topic-${topicCssClass}"
+            class="layout__content curriculum-layout__content curriculum-content-container curriculum-module topic-${topicCssClass}"
             lang=${doc.locale}
           >
-            <header class="curriculum-layout__header curriculum-content">
+            <header
+              class="layout__header curriculum-layout__header curriculum-content"
+            >
               ${doc?.topic ? renderTopicIcon(context, doc.topic) : nothing}
               <h1>${doc?.title}</h1>
               ${doc?.topic
@@ -48,16 +52,21 @@ export class CurriculumModule extends ServerComponent {
                 ? html`<p class="module-group">${doc.group}</p>`
                 : nothing}
             </header>
-            <aside class="curriculum-layout__toc">
+            <aside class="layout__right-sidebar curriculum-layout__toc">
               ${toc}
               <mdn-placement-sidebar></mdn-placement-sidebar>
             </aside>
-            <div class="curriculum-layout__body curriculum-content">
+            <div
+              class="layout__body curriculum-layout__body curriculum-content"
+            >
               ${renderCurriculumBody(context, doc)}
               ${this.renderPrevNext(context, doc)}
             </div>
           </main>
-          <aside class="curriculum-layout__sidebar" id="main-sidebar">
+          <aside
+            class="layout__left-sidebar curriculum-layout__sidebar"
+            id="main-sidebar"
+          >
             ${sidebar}
           </aside>
         </div>
diff --git a/components/curriculum-overview/server.js b/components/curriculum-overview/server.js
index 9d865b0d3..f8784cfbd 100644
--- a/components/curriculum-overview/server.js
+++ b/components/curriculum-overview/server.js
@@ -36,22 +36,28 @@ export class CurriculumOverview extends ServerComponent {
     return PageLayout.render(
       context,
       html`
-        <div class="curriculum-layout curriculum-content-container">
+        <div
+          class="layout__2-sidebars-inline curriculum-layout curriculum-content-container"
+        >
           <main
             id="content"
-            class="curriculum-layout__content curriculum-content-container curriculum-overview topic-${topicCssClass}"
+            class="layout__content curriculum-layout__content curriculum-content-container curriculum-overview topic-${topicCssClass}"
             lang=${doc.locale}
           >
-            <header class="curriculum-layout__header curriculum-content">
+            <header
+              class="layout__header curriculum-layout__header curriculum-content"
+            >
               <h1><span>${coloredTitle}</span> ${restTitle}</h1>
             </header>
 
-            <aside class="curriculum-layout__toc">
+            <aside class="layout__right-sidebar curriculum-layout__toc">
               ${toc}
               <mdn-placement-sidebar></mdn-placement-sidebar>
             </aside>
 
-            <div class="curriculum-layout__body curriculum-content">
+            <div
+              class="layout__body curriculum-layout__body curriculum-content"
+            >
               ${renderCurriculumBody(context, doc)}
               ${doc?.modules && doc.modules.length > 0
                 ? html`
@@ -65,41 +71,14 @@ export class CurriculumOverview extends ServerComponent {
             </div>
           </main>
 
-          <aside class="curriculum-layout__sidebar" id="main-sidebar">
+          <aside
+            class="layout__left-sidebar curriculum-layout__sidebar"
+            id="main-sidebar"
+          >
             ${sidebar}
           </aside>
         </div>
       `,
-
-      // html`
-      //   <main
-      //     id="content"
-      //     class="curriculum-content-container container curriculum-overview topic-${topicCssClass}"
-      //   >
-      //     ${sidebar}
-      //     <article id="content" class="curriculum-content" lang=${doc.locale}>
-      //       <header>
-      //         <h1><span>${coloredTitle}</span> ${restTitle}</h1>
-      //       </header>
-      //       ${renderCurriculumBody(context, doc)}
-      //       ${doc?.modules && doc.modules.length > 0
-      //         ? html`
-      //             <section class="module-contents">
-      //               <h2>Module list</h2>
-      //               ${renderModulesList(context, doc.modules)}
-      //             </section>
-      //           `
-      //         : nothing}
-      //       ${this.renderPrevNext(context, doc)}
-      //     </article>
-      //     <div class="toc-container">
-      //       <aside class="toc">
-      //         <nav>${toc}</nav>
-      //       </aside>
-      //       <mdn-placement-sidebar></mdn-placement-sidebar>
-      //     </div>
-      //   </main>
-      // `,
     );
   }
 
diff --git a/components/curriculum/layout.css b/components/curriculum/layout.css
index 700cd4c76..646c0dad6 100644
--- a/components/curriculum/layout.css
+++ b/components/curriculum/layout.css
@@ -1,39 +1,12 @@
-.curriculum-content-container {
-  display: grid;
-
-  grid-template-areas:
-    "sidebar . header . toc"
-    "sidebar . body   . toc";
-  grid-template-rows: min-content auto;
-  grid-template-columns: var(--layout-2-sidebars);
-
-  justify-content: space-between;
-
-  padding-inline: var(--layout-side-padding);
-
-  .curriculum-layout__content {
-    display: contents;
-  }
-
-  .curriculum-layout__header {
-    grid-area: header;
-  }
+@import url("../layout/2-sidebars.css");
 
+.curriculum-content-container {
   .curriculum-layout__body {
-    grid-area: body;
     padding-bottom: 3rem;
   }
 
   .curriculum-layout__sidebar {
-    grid-area: sidebar;
     padding-top: 0;
-
-    @media (--screen-layout-2-sidebars) {
-      .left-sidebar {
-        padding-right: calc(var(--layout-sidebar-gap) / 2);
-        margin-right: calc(var(--layout-sidebar-gap) / -2);
-      }
-    }
   }
 
   .curriculum-layout__toc {
@@ -41,62 +14,14 @@
 
     flex-wrap: wrap;
 
-    grid-area: toc;
-
     gap: 0.5rem;
     align-content: start;
     align-items: start;
     justify-content: space-between;
   }
 
-  .curriculum-layout__sidebar .left-sidebar,
-  .curriculum-layout__toc {
-    position: sticky;
-    top: var(--sticky-header-height);
-
-    max-height: calc(100vh - var(--sticky-header-height));
-
-    overflow-y: auto;
-  }
-
-  @media (--screen-layout-1-sidebar-or-less) {
-    grid-template-areas:
-      "toc . header"
-      "toc . body";
-    grid-template-columns: var(--layout-1-sidebar-left);
-
-    .curriculum-layout__sidebar {
-      z-index: 1;
-
-      display: none;
-
-      grid-area: toc;
-
-      background: var(--color-background-page);
-    }
-  }
-
   @media (--screen-layout-no-sidebar) {
-    display: block;
-
-    .curriculum-layout__sidebar {
-      position: fixed;
-      inset: 0;
-      top: var(--sticky-header-height);
-      z-index: var(--z-index-sidebar-mobile);
-
-      .left-sidebar {
-        padding: 1rem;
-      }
-    }
-
     .curriculum-layout__toc {
-      position: unset;
-      top: unset;
-
-      max-height: unset;
-
-      overflow-y: unset;
       --toc-header-font-size: var(--font-size-larger);
     }
   }
diff --git a/components/curriculum/sidebar.css b/components/curriculum/sidebar.css
index f7e855fdf..b972aaf76 100644
--- a/components/curriculum/sidebar.css
+++ b/components/curriculum/sidebar.css
@@ -1,9 +1,5 @@
 .curriculum-content-container .left-sidebar {
-  position: sticky;
-  top: var(--sticky-header-height);
-
   padding-bottom: 3rem;
-
   overflow-wrap: anywhere;
 
   ol {
diff --git a/components/curriculum/toc.css b/components/curriculum/toc.css
index d99941931..af7779f60 100644
--- a/components/curriculum/toc.css
+++ b/components/curriculum/toc.css
@@ -1,7 +1,5 @@
 .curriculum-content-container {
   .curriculum-layout__toc {
-    padding: 2px;
-
     .document-toc {
       padding: 0;
       margin-bottom: 2rem;
@@ -83,7 +81,7 @@
         }
       }
 
-      @media (--screen-small-and-narrower) {
+      @media (--screen-layout-no-sidebar) {
         padding: 0 1rem;
       }
 

From 867eb919e80154df52591fa918db1545552b3748 Mon Sep 17 00:00:00 2001
From: Leo McArdle <leo@mozilla.com>
Date: Wed, 10 Dec 2025 18:23:25 +0000
Subject: [PATCH 11/12] update readme

---
 components/layout/README.md | 62 +++++++++++++++++++++++++++++++------
 1 file changed, 52 insertions(+), 10 deletions(-)

diff --git a/components/layout/README.md b/components/layout/README.md
index 320178d1b..bf4f3399e 100644
--- a/components/layout/README.md
+++ b/components/layout/README.md
@@ -1,8 +1,50 @@
 # Layout
 
-This component provides some global utility variables for consistent layout.
+This component provides some global utility variables and some importable stylesheets for consistent layout.
 
-## Side padding
+If you need to do something very custom, you can use the variables directly, otherwise we recommend using one of the importable stylesheets and applying the classes to your component.
+
+## Class based layouts
+
+### `.layout__2-sidebars`
+
+Import from `./2-sidebars.css`
+
+Classes should be used with this hierarchy:
+
+- `layout__2-sidebars`
+  - `layout__left-sidebar`
+  - `layout__content`
+  - `layout__right-sidebar`
+
+When there's space for 2 sidebars then both sidebars will show, left on the left and right on the right.
+
+When there's only space for 1 sidebar then the right sidebar will show on the left and the left sidebar will become toggleable with `<mdn-toggle-sidebar>`.
+
+When there's no space for sidebars then the right sidebar will be hidden and the left sidebar still toggleable.
+
+### `.layout__2-sidebars-inline`
+
+Import from `./2-sidebars.css`
+
+Classes should be used with this hierarchy:
+
+- `layout__2-sidebars-inline`
+  - `layout__left-sidebar`
+  - `layout__content`
+    - `layout__header`
+    - `layout__right-sidebar`
+    - `layout__body`
+
+When there's space for 2 sidebars then both sidebars will show, left on the left and right on the right, with header and body shown in the central content area.
+
+When there's only space for 1 sidebar then the right sidebar will show on the left and the left sidebar will become toggleable with `<mdn-toggle-sidebar>`.
+
+When there's no space for sidebars then the right sidebar will be displayed inline within the content and the left sidebar still toggleable.
+
+## Global utility variables
+
+### Side padding
 
 In the simplest case, you may just need the `--layout-side-padding` variable. This keeps full width content in line with the padding in the navigation and footer, which provides a small padding on small screens, and centers content on very large screens:
 
@@ -12,7 +54,7 @@ In the simplest case, you may just need the `--layout-side-padding` variable. Th
 }
 ```
 
-## Content and sidebar layouts
+### Content and sidebar layouts
 
 If the page has "content" - some kind of prose - and optionally sidebars, you'll likely want one of the following layouts.
 The columns are sized to ensure that the content column doesn't become too wide (and have unreadably long lines of text), and that the sidebar columns don't become too narrow.
@@ -57,7 +99,7 @@ If you're using sidebars, you'll probably want to use the [custom media queries]
 }
 ```
 
-### 2 sidebars: `--layout-2-sidebars`
+#### 2 sidebars: `--layout-2-sidebars`
 
 A column for content, two columns for sidebars, and two columns for a gap between the content and sidebars. The columns are named as follows:
 
@@ -69,13 +111,13 @@ A column for content, two columns for sidebars, and two columns for a gap betwee
 
 Use the `--screen-layout-1-sidebar-or-less` custom media query to change to a different layout when the viewport becomes too narrow.
 
-### 1 sidebar
+#### 1 sidebar
 
 Two variants, which are identical apart from one having a left sidebar and the other a right sidebar. They have a column for content, a column for the sidebar, and a column for a gap between the content and sidebar.
 
 Use the `--screen-layout-no-sidebar` custom media query to change to a different layout when the viewport becomes too narrow.
 
-#### Left sidebar `--layout-1-sidebar-left`
+##### Left sidebar `--layout-1-sidebar-left`
 
 The columns are named as follows:
 
@@ -86,7 +128,7 @@ The columns are named as follows:
 | left-sidebar |      |         |
 |   sidebar    |      |         |
 
-#### Right sidebar `--layout-1-sidebar-right`
+##### Right sidebar `--layout-1-sidebar-right`
 
 The columns are named as follows:
 
@@ -97,11 +139,11 @@ The columns are named as follows:
 |         |      | right-sidebar |
 |         |      |    sidebar    |
 
-### No sidebar
+#### No sidebar
 
 Two variants, one if you're using `--layout-side-padding`, the other if you'd like to place things within that padding (e.g. a full width banner):
 
-#### Using padding: `--layout-no-sidebar`
+##### Using padding: `--layout-no-sidebar`
 
 The columns are named as follows:
 
@@ -122,7 +164,7 @@ The columns are named as follows:
 }
 ```
 
-#### Not using padding: `--layout-no-sidebar-extended`
+##### Not using padding: `--layout-no-sidebar-extended`
 
 The columns are named as follows:
 

From d07c4c62703668009fbb7ff0f2bdf9d05001f31d Mon Sep 17 00:00:00 2001
From: Leo McArdle <leo@mozilla.com>
Date: Tue, 3 Feb 2026 17:51:43 +0000
Subject: [PATCH 12/12] fix observatory docs sidebar padding

---
 components/generic-layout/server.css  | 5 -----
 components/generic-sidebar/server.css | 2 +-
 2 files changed, 1 insertion(+), 6 deletions(-)

diff --git a/components/generic-layout/server.css b/components/generic-layout/server.css
index 71a34fe07..f7b210f27 100644
--- a/components/generic-layout/server.css
+++ b/components/generic-layout/server.css
@@ -2,11 +2,6 @@
 
 /* Generic Layout */
 
-/* Sidebar */
-.generic-layout__sidebar {
-  padding-block: 2rem;
-}
-
 /* Content */
 .generic-layout__content {
   padding-block: 2rem;
diff --git a/components/generic-sidebar/server.css b/components/generic-sidebar/server.css
index 19fc1605d..df1c13679 100644
--- a/components/generic-sidebar/server.css
+++ b/components/generic-sidebar/server.css
@@ -2,7 +2,7 @@
   --color-accent: var(--color-blue-50);
   --color-background-accent: var(--color-background-blue);
   --color-border-items: light-dark(var(--color-gray-80), var(--color-gray-20));
-
+  padding-block: 2rem;
   margin-bottom: 2rem;
 
   .generic-sidebar__header {