docs: drop contents rail, cap nav at 16rem, add design rules

docs/_config.yml

@@ -58,17 +58,17 @@ sphinx:
       - Quartz
     suppress_warnings:
       - "etoc.toctree"
-    # In-page Contents sidebar
+    # No in-page Contents sidebar: the pages showcase wide interactive
+    # widgets, so the article column gets every horizontal pixel.
     html_theme_options:
-      secondary_sidebar_items: ["page-toc"]
+      secondary_sidebar_items: []
     html_static_path:
       - "_static"
     html_extra_path:
       - "_extra"
     html_css_files:
       - custom.css
     html_js_files:
-      - toc-toggle.js
       # Keeps the mobile hamburger wired across sphinx theme drift; the file
       # is idempotent so double-inclusion via _static auto-add is harmless.
       - nav-toggle-fix.js

docs/_static/custom.css

@@ -1,5 +1,15 @@
-/* Interactive widgets are wide. Give the article the full page width and let
-   any still-wider output scroll horizontally instead of being clipped. */
+/* Interactive widgets are wide. Give the article the full page width, drop the
+   right-hand in-page "Contents" sidebar, and let any still-wider output scroll
+   horizontally instead of being clipped. */
+
+/* Remove the secondary (right) table-of-contents sidebar. Deliberate: the
+   pages showcase wide interactive widgets, so every horizontal pixel goes to
+   the article column. Do not reintroduce a page-toc rail. */
+.bd-sidebar-secondary,
+.bd-toc,
+div.bd-sidebar-secondary {
+  display: none !important;
+}
 
 /* Use the full available width for the page and article columns. */
 .bd-page-width,
@@ -9,10 +19,20 @@
   max-width: 100% !important;
 }
 
-/* Contents sidebar toggle */
+/* Left navigation: fixed 16rem width on desktop — it must NOT scale
+   proportionally with the viewport (the theme's default is a percentage, so
+   big monitors waste pixels on nav that belong to widgets). The collapse
+   offset is overridden IN LOCKSTEP with the width: if they ever disagree,
+   the collapsed state drags the whole article off-screen (burned twice).
+   Mobile (<960px) keeps the theme's off-canvas drawer untouched. */
 @media (min-width: 960px) {
-  html.toc-hidden .bd-sidebar-secondary {
-    display: none !important;
+  .bd-sidebar-primary {
+    width: 16rem;
+    max-width: 16rem;
+    flex: 0 0 16rem;
+  }
+  .bd-sidebar-primary.pst-sidebar-hidden {
+    margin-left: -16rem;
   }
 }
 

docs/_toc.yml

@@ -78,6 +78,8 @@ parts:
       - file: maintainer/index
         title: Maintainer guide
         sections:
+          - file: maintainer/docs-design
+            title: Docs design rules
           - file: changelog
             title: Changelog
           - file: maintainer/widget-release

docs/maintainer/docs-design.md

@@ -0,0 +1,55 @@
+# Docs Design Rules
+
+Non-negotiable layout rules for this docs site. They exist because each one
+was broken at least once and reached the published site. Fix forward from the
+existing design — do not reinvent it during theme bumps or reworks.
+
+## Widgets get the horizontal pixels
+
+The pages exist to showcase wide interactive widgets. Every layout decision
+gives spare width to the article column, not to chrome.
+
+- **No right-hand "Contents" (page-toc) sidebar. Ever.**
+  `docs/_static/custom.css` hides `.bd-sidebar-secondary`, and
+  `docs/_config.yml` sets `secondary_sidebar_items: []`. A "hideable
+  contents" rework reintroduced it once (2026-07-30) and was reverted the
+  same day. Do not add a page-toc rail, a toc toggle button, or a
+  `toc-toggle.js` back.
+- **Left navigation is fixed at 16rem on desktop — never proportional.**
+  The theme's default sidebar width is a percentage of the viewport, so big
+  monitors silently spend hundreds of pixels on nav. `custom.css` pins
+  `width / max-width / flex-basis` to `16rem` at `min-width: 960px`.
+
+## Width and collapse offset move in lockstep
+
+If the sidebar's laid-out width and the theme's collapsed offset disagree,
+the whole article is dragged off-screen by the difference (shipped broken
+twice: −25px on phones, −116px on desktops). `custom.css` therefore overrides
+`.pst-sidebar-hidden { margin-left: -16rem; }` right next to the 16rem width.
+Change one, change both. Below 960px the theme's off-canvas drawer is left
+completely alone.
+
+## The mobile hamburger must survive theme drift
+
+Both sphinx themes wire the drawer to `document.querySelector('.primary-toggle')`
+— the first match — and newer pydata themes render an extra hidden button
+first, killing the visible hamburger. Two defenses, keep both:
+
+- `docs/_static/nav-toggle-fix.js` forwards clicks from unwired toggle
+  buttons to the wired one (idempotent, safe to double-load).
+- `scripts/check_docs_nav_toggle.py` runs in the docs workflow after every
+  build and fails the deploy when a page has multiple toggles without the
+  shim.
+
+## Verify locally before any push
+
+CI is never the first build. Before pushing docs changes:
+
+1. `scripts/docs_preview.sh` (full build + no-store server on port 8767);
+   for CSS-only tweaks, `--no-build` and copy the asset into
+   `docs/_build/html/_static/`.
+2. Drive the built pages at phone (375/420), laptop (~1500), and large
+   desktop (~1900) widths — with the left sidebar **both expanded and
+   collapsed**, and the phone drawer opened and closed.
+3. `python scripts/check_docs_nav_toggle.py docs/_build/html` must pass, and
+   built pages must contain zero `img.quantem-static-fallback` elements.