From 0d7d8712cf0475b8e879cf672f90cbf8ee9e91bc Mon Sep 17 00:00:00 2001
From: Jonathan Peris <jperis.silva@gmail.com>
Date: Sat, 2 May 2026 22:42:13 -0300
Subject: [PATCH] fix(docs): standardize missing accessibility and UX features

Add prefers-reduced-motion CSS media queries, Firefox scrollbar support,
window.__docsSlug for route-based deep links, scrollspy nav auto-scroll,
and mobile menu close on nav click to match standardized pattern
---
 docs/src/pages/docs/[...slug].astro | 44 ++++++++++++++++++++---------
 docs/src/styles/docs.css            | 43 ++++++++++++++++++++++++++++
 2 files changed, 74 insertions(+), 13 deletions(-)

diff --git a/docs/src/pages/docs/[...slug].astro b/docs/src/pages/docs/[...slug].astro
index 143aea7..19bb7e2 100644
--- a/docs/src/pages/docs/[...slug].astro
+++ b/docs/src/pages/docs/[...slug].astro
@@ -124,6 +124,8 @@ const docsBase = Astro.site
     </div>
   </div>
 
+  {requestedSlug && <script is:inline define:vars={{ slug: requestedSlug, isRoot: isRoot }}>window.__docsSlug = slug; window.__isRoot = isRoot;</script>}
+
   <script is:inline define:vars={{ isRoot, docsBase }}>
     document.addEventListener('DOMContentLoaded', function () {
       const sections = document.querySelectorAll('section.doc-section');
@@ -132,6 +134,7 @@ const docsBase = Astro.site
       const sidebar = document.getElementById('sidebar');
       const overlay = document.getElementById('overlay');
       const searchBox = document.getElementById('searchBox');
+      const isRoot = window.__isRoot !== false;
       const prefersReducedMotion = !window.matchMedia('(prefers-reduced-motion: no-preference)').matches;
 
       /* Mobile menu toggle */
@@ -147,30 +150,35 @@ const docsBase = Astro.site
           menuToggle.setAttribute('aria-expanded', String(isOpen));
         });
         overlay.addEventListener('click', closeMenu);
-        navItems.forEach(function (item) {
-          item.addEventListener('click', closeMenu);
-        });
       }
 
-      /* Auto-scroll to hash section (root only) */
-      if (isRoot && window.location.hash) {
-        const targetId = window.location.hash.slice(1);
-        const target = document.getElementById(targetId);
-        if (target) {
-          setTimeout(function () {
-            target.scrollIntoView({ behavior: prefersReducedMotion ? 'auto' : 'smooth' });
-          }, 100);
+      /* Auto-scroll to section (root only) */
+      if (isRoot) {
+        const targetSlug = window.__docsSlug;
+        const hash = window.location.hash;
+        const sectionId = targetSlug || (hash && hash.length > 1 ? hash.slice(1) : null);
+        if (sectionId) {
+          const target = document.getElementById(sectionId);
+          if (target) {
+            setTimeout(function () {
+              target.scrollIntoView({ behavior: prefersReducedMotion ? 'auto' : 'smooth' });
+            }, 100);
+          }
         }
       }
 
-      /* Scrollspy (root + multi-section only) */
+      /* Scrollspy + nav click (root + multi-section only) */
       if (isRoot && sections.length > 1) {
         const observer = new IntersectionObserver(
           function (entries) {
             entries.forEach(function (entry) {
               if (entry.isIntersecting) {
                 navItems.forEach(function (item) {
-                  item.classList.toggle('active', item.getAttribute('data-nav-id') === entry.target.id);
+                  var isActive = item.getAttribute('data-nav-id') === entry.target.id;
+                  item.classList.toggle('active', isActive);
+                  if (isActive) {
+                    item.scrollIntoView({ behavior: prefersReducedMotion ? 'auto' : 'smooth', block: 'nearest' });
+                  }
                 });
               }
             });
@@ -178,6 +186,16 @@ const docsBase = Astro.site
           { root: null, rootMargin: '-80px 0px -60% 0px', threshold: 0 }
         );
         sections.forEach(function (section) { observer.observe(section); });
+
+        navItems.forEach(function (item) {
+          item.addEventListener('click', function () {
+            if (window.innerWidth <= 768 && menuToggle && sidebar && overlay) {
+              sidebar.classList.remove('open');
+              overlay.classList.remove('open');
+              menuToggle.setAttribute('aria-expanded', 'false');
+            }
+          });
+        });
       }
 
       /* Search filter (root only) */
diff --git a/docs/src/styles/docs.css b/docs/src/styles/docs.css
index defd3ab..1fdf247 100644
--- a/docs/src/styles/docs.css
+++ b/docs/src/styles/docs.css
@@ -353,6 +353,49 @@
   z-index: 95;
 }
 
+/* ── Scroll behavior / reduced motion ──────────────────────────────── */
+@media (prefers-reduced-motion: no-preference) {
+  html { scroll-behavior: smooth; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0s !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0s !important;
+  }
+}
+
+/* ── Custom scrollbar ─────────────────────────────────────────────── */
+html {
+  scrollbar-color: var(--rust-orange) var(--bg-deep);
+  scrollbar-width: thin;
+}
+
+::-webkit-scrollbar {
+  width: 6px;
+  height: 6px;
+}
+
+::-webkit-scrollbar-track {
+  background: var(--bg-deep);
+  border-left: 1px solid rgba(45, 26, 0, 0.5);
+}
+
+::-webkit-scrollbar-thumb {
+  background: var(--rust-orange);
+  border-radius: 3px;
+  transition: background 0.2s;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: #DEA584;
+}
+
+::-webkit-scrollbar-corner {
+  background: var(--bg-deep);
+}
+
 /* ── Scrollbar (docs sidebar) ──────────────────────────────────────── */
 .docs-layout .sidebar::-webkit-scrollbar {
   width: 4px;