From 30e893fa6ec0e9c04f9e575359a2b4693e739366 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 19 Oct 2026 11:15:40 +0800
Subject: [PATCH] feat(web): auto-hiding responsive header, flatter install
 command

Header
- Sticky bar that slides out on scroll down and comes back on the first
  small scroll up (and always near the top). Never hides while the mobile
  menu is open. Respects prefers-reduced-motion; stays visible without JS.
- Phones get a menu button (44px target) with a stacked link panel that
  closes on link click, Escape, outside tap and resize to desktop.
- Sticky sidebar, mobile contents bar and the Commands title now sit below
  the header only while it is showing (--sticky-offset).
- Anchors land below the header (scroll-padding / scroll-margin).
- Fix: the mobile docs contents bar never stuck because its wrapper was a
  box of its own; the wrapper now uses display: contents below 760px.

Install command
- Replace the outlined box + black button with a single line of type on a
  rule; the whole row is the copy target, with a copy/check icon.
- Hero note: the API key is optional and only adds the AI layer, instead of
  "No account or API key".

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019HJc4sv9pSLh7vhduSUxBE
---
 .../web/src/components/docs/DocsSidebar.astro |  10 +-
 .../components/landing/CommandsSection.astro  |   3 +-
 .../src/components/landing/CopyCommand.astro  | 134 ++++++----
 .../src/components/landing/HeroSection.astro  |   8 +-
 .../src/components/landing/SiteHeader.astro   | 240 ++++++++++++++++--
 apps/web/src/pages/docs.astro                 |  11 +
 apps/web/src/styles/docs-prose.css            |  11 +-
 apps/web/src/styles/global.css                |  10 +-
 8 files changed, 352 insertions(+), 75 deletions(-)

diff --git a/apps/web/src/components/docs/DocsSidebar.astro b/apps/web/src/components/docs/DocsSidebar.astro
index 41cd1f5..352b69e 100644
--- a/apps/web/src/components/docs/DocsSidebar.astro
+++ b/apps/web/src/components/docs/DocsSidebar.astro
@@ -99,8 +99,9 @@ const tree = buildTree(headings);
 <style>
   .docs-sidebar {
     position: sticky;
-    top: 2rem;
-    max-height: calc(100vh - 4rem);
+    top: calc(2rem + var(--sticky-offset));
+    max-height: calc(100vh - 4rem - var(--sticky-offset));
+    transition: top 260ms cubic-bezier(0.2, 0.7, 0.2, 1);
     overflow-y: auto;
   }
 
@@ -108,15 +109,16 @@ const tree = buildTree(headings);
     display: none;
   }
 
-  @media (max-width: 760px) {
+  @media (max-width: 759px) {
     .docs-sidebar {
       display: none;
     }
 
     .docs-mobile-toc-wrap {
       position: sticky;
-      top: 0;
+      top: var(--sticky-offset);
       z-index: 40;
+      transition: top 260ms cubic-bezier(0.2, 0.7, 0.2, 1);
       padding-block: 0.5rem;
       background: var(--paper);
       display: block;
diff --git a/apps/web/src/components/landing/CommandsSection.astro b/apps/web/src/components/landing/CommandsSection.astro
index 1eabb0b..da49afb 100644
--- a/apps/web/src/components/landing/CommandsSection.astro
+++ b/apps/web/src/components/landing/CommandsSection.astro
@@ -40,7 +40,8 @@ const commands = [
 
     .commands__title {
       position: sticky;
-      top: 2rem;
+      top: calc(2rem + var(--sticky-offset));
+      transition: top 260ms cubic-bezier(0.2, 0.7, 0.2, 1);
     }
   }
 
diff --git a/apps/web/src/components/landing/CopyCommand.astro b/apps/web/src/components/landing/CopyCommand.astro
index 8c67db9..163300b 100644
--- a/apps/web/src/components/landing/CopyCommand.astro
+++ b/apps/web/src/components/landing/CopyCommand.astro
@@ -13,8 +13,17 @@ const { command, size = "base" } = Astro.props;
     <span class="copy__text">{command}</span>
   </code>
   <button type="button" class="copy__button" aria-label={`Copy ${command}`}>
-    <span class="copy__idle">Copy</span>
-    <span class="copy__done" aria-hidden="true">Copied</span>
+    <svg class="copy__icon copy__icon--copy" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true">
+      <rect x="5.25" y="5.25" width="8" height="8" rx="1.5" fill="none" stroke="currentColor" stroke-width="1.5" />
+      <path d="M10.75 3.5v-.25A1.5 1.5 0 0 0 9.25 1.75h-5.5a1.5 1.5 0 0 0-1.5 1.5v5.5a1.5 1.5 0 0 0 1.5 1.5H4" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" />
+    </svg>
+    <svg class="copy__icon copy__icon--check" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true">
+      <path d="m3 8.5 3.25 3.25L13 4.75" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" />
+    </svg>
+    <span class="copy__label">
+      <span class="copy__idle">Copy</span>
+      <span class="copy__done" aria-hidden="true">Copied</span>
+    </span>
   </button>
 </div>
 
@@ -29,94 +38,123 @@ const { command, size = "base" } = Astro.props;
 </script>
 
 <style>
+  /*
+   * One line of type sitting on a rule, not a box. The whole row is the click
+   * target (the button stretches over it), and the rule turns blue on hover.
+   */
   .copy {
-    display: inline-flex;
-    align-items: stretch;
-    max-width: 100%;
-    border: 1px solid var(--ink);
-    border-radius: var(--radius);
-    background: var(--paper);
+    position: relative;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 1.5rem;
+    width: min(100%, 30rem);
+    padding-bottom: 0.7rem;
+    border-bottom: 1px solid var(--ink);
+    transition: border-color 150ms ease;
+  }
+
+  .copy:hover,
+  .copy:has(.copy__button:focus-visible) {
+    border-bottom-color: var(--accent);
   }
 
   .copy__line {
-    display: flex;
-    align-items: center;
-    gap: 0.75ch;
     min-width: 0;
-    padding: 0.8rem 1rem;
-    font-size: 0.9375rem;
+    font-size: 1.0625rem;
     color: var(--ink);
-    overflow-x: auto;
-    white-space: nowrap;
+    overflow-wrap: anywhere;
   }
 
   .copy__prompt {
-    color: var(--accent);
+    margin-right: 0.9ch;
+    color: var(--muted);
   }
 
   .copy__button {
     flex: none;
-    min-width: 5.5rem;
-    padding: 0 1rem;
+    display: inline-flex;
+    align-items: center;
+    gap: 0.45rem;
+    padding: 0;
     border: 0;
-    border-left: 1px solid var(--ink);
-    border-radius: 0 calc(var(--radius) - 1px) calc(var(--radius) - 1px) 0;
-    background: var(--ink);
-    color: var(--paper);
+    background: none;
+    color: var(--muted);
     font-family: var(--font-body);
     font-size: 0.9375rem;
-    font-weight: 500;
     cursor: pointer;
-    transition: background 150ms ease;
+    transition: color 150ms ease;
   }
 
-  .copy__button:hover {
-    background: var(--accent);
+  /* Stretch the hit area over the whole row. */
+  .copy__button::after {
+    content: "";
+    position: absolute;
+    inset: -0.5rem 0 0;
+  }
+
+  .copy__button:focus-visible {
+    outline: none;
+  }
+
+  .copy__button:focus-visible::after {
+    outline: 2px solid var(--accent);
+    outline-offset: 4px;
+  }
+
+  .copy:hover .copy__button {
+    color: var(--accent);
   }
 
+  .copy__icon {
+    flex: none;
+  }
+
+  .copy__icon--check,
   .copy__done,
+  .copy__button[data-copied] .copy__icon--copy,
   .copy__button[data-copied] .copy__idle {
     display: none;
   }
 
+  .copy__button[data-copied] {
+    color: var(--accent);
+  }
+
+  .copy__button[data-copied] .copy__icon--check {
+    display: block;
+  }
+
   .copy__button[data-copied] .copy__done {
     display: inline;
   }
 
-  /* On narrow screens let the command wrap instead of hiding its tail. */
-  @media (max-width: 40rem) {
-    .copy__line {
-      align-items: flex-start;
-      padding: 0.75rem;
-      font-size: 0.8125rem;
-      white-space: normal;
-      overflow-wrap: anywhere;
-    }
-
-    .copy__button {
-      min-width: 4.5rem;
-      padding: 0 0.75rem;
-    }
+  /* Large: the command is the headline of its section. */
+  .copy--large {
+    width: min(100%, 52rem);
+    padding-bottom: 1.1rem;
   }
 
   .copy--large .copy__line {
-    padding: 1.1rem 1.4rem;
-    font-size: clamp(1rem, 2.6vw, 1.75rem);
+    font-size: clamp(1.25rem, 4.6vw, 2.75rem);
+    letter-spacing: -0.03em;
   }
 
   .copy--large .copy__button {
-    min-width: 7rem;
     font-size: 1.0625rem;
   }
 
   @media (max-width: 40rem) {
-    .copy--large .copy__line {
-      padding: 0.9rem 0.75rem;
-      font-size: 1rem;
+    .copy {
+      gap: 1rem;
     }
 
-    .copy--large .copy__button {
-      min-width: 4.5rem;
+    .copy__line {
+      font-size: 0.9375rem;
+    }
+
+    .copy--large .copy__line {
+      font-size: clamp(0.9375rem, 4.2vw, 1.5rem);
     }
   }
 </style>
diff --git a/apps/web/src/components/landing/HeroSection.astro b/apps/web/src/components/landing/HeroSection.astro
index 108d1de..3793582 100644
--- a/apps/web/src/components/landing/HeroSection.astro
+++ b/apps/web/src/components/landing/HeroSection.astro
@@ -19,7 +19,7 @@ import CopyCommand from "./CopyCommand.astro";
     <a class="link" href="https://github.com/itsflaid/devmap">Source on GitHub</a>
   </div>
 
-  <p class="hero__note">Needs Node 22 or newer. No account or API key to analyze.</p>
+  <p class="hero__note">Needs Node 22 or newer. An API key is optional and only adds the AI layer.</p>
 </section>
 
 <style>
@@ -74,9 +74,9 @@ import CopyCommand from "./CopyCommand.astro";
   .hero__install {
     display: flex;
     flex-wrap: wrap;
-    align-items: center;
-    gap: 1rem 2rem;
-    margin-top: 2rem;
+    align-items: baseline;
+    gap: 1.25rem 2.5rem;
+    margin-top: 2.25rem;
   }
 
   .hero__note {
diff --git a/apps/web/src/components/landing/SiteHeader.astro b/apps/web/src/components/landing/SiteHeader.astro
index ccf631f..e1a603d 100644
--- a/apps/web/src/components/landing/SiteHeader.astro
+++ b/apps/web/src/components/landing/SiteHeader.astro
@@ -6,26 +6,148 @@ const links = [
 ];
 ---
 
-<header class="header page">
-  <a class="header__brand" href="/" aria-label="DevMap home">
-    <img src="/logo-mark.png" alt="" width="28" height="28" />
-    <span>devmap</span>
-  </a>
-
-  <nav class="header__nav" aria-label="Primary">
-    {links.map((link) => <a href={link.href}>{link.label}</a>)}
-  </nav>
+<header class="site-header" data-site-header>
+  <div class="site-header__bar page">
+    <a class="site-header__brand" href="/" aria-label="DevMap home">
+      <img src="/logo-mark.png" alt="" width="28" height="28" />
+      <span>devmap</span>
+    </a>
+
+    <nav class="site-header__nav" id="site-nav" aria-label="Primary">
+      {links.map((link) => <a href={link.href}>{link.label}</a>)}
+    </nav>
+
+    <button
+      type="button"
+      class="site-header__toggle"
+      aria-expanded="false"
+      aria-controls="site-nav"
+      aria-label="Open menu"
+    >
+      <span class="site-header__toggle-bar"></span>
+      <span class="site-header__toggle-bar"></span>
+    </button>
+  </div>
 </header>
 
+<script>
+  const header = document.querySelector<HTMLElement>("[data-site-header]");
+  const toggle = header?.querySelector<HTMLButtonElement>(".site-header__toggle");
+  const nav = header?.querySelector<HTMLElement>(".site-header__nav");
+  const root = document.documentElement;
+
+  if (header && toggle && nav) {
+    // Tuned so a small flick upward brings the bar back at once, while
+    // reading downward (even with a jittery trackpad) keeps it out of the way.
+    const HIDE_AFTER = 96;
+    const DOWN_STEP = 6;
+    const UP_STEP = 3;
+
+    let lastY = window.scrollY;
+    let ticking = false;
+    let menuOpen = false;
+
+    const setShown = (shown: boolean) => {
+      header.classList.toggle("is-hidden", !shown);
+      root.dataset.header = shown ? "shown" : "hidden";
+    };
+
+    const setMenu = (open: boolean) => {
+      menuOpen = open;
+      header.classList.toggle("is-open", open);
+      toggle.setAttribute("aria-expanded", String(open));
+      toggle.setAttribute("aria-label", open ? "Close menu" : "Open menu");
+      if (open) setShown(true);
+    };
+
+    const update = () => {
+      ticking = false;
+      // iOS rubber-banding reports values outside the scrollable range.
+      const maxY = document.documentElement.scrollHeight - window.innerHeight;
+      const y = Math.min(Math.max(window.scrollY, 0), Math.max(maxY, 0));
+      const delta = y - lastY;
+
+      header.classList.toggle("is-stuck", y > 0);
+
+      if (y <= HIDE_AFTER) {
+        setShown(true);
+      } else if (delta >= DOWN_STEP && !menuOpen) {
+        setShown(false);
+      } else if (delta <= -UP_STEP) {
+        setShown(true);
+      }
+
+      if (Math.abs(delta) >= UP_STEP) lastY = y;
+    };
+
+    window.addEventListener(
+      "scroll",
+      () => {
+        if (!ticking) {
+          ticking = true;
+          window.requestAnimationFrame(update);
+        }
+      },
+      { passive: true }
+    );
+
+    toggle.addEventListener("click", () => setMenu(!menuOpen));
+
+    nav.querySelectorAll("a").forEach((link) =>
+      link.addEventListener("click", () => setMenu(false))
+    );
+
+    document.addEventListener("keydown", (event) => {
+      if (event.key === "Escape" && menuOpen) {
+        setMenu(false);
+        toggle.focus();
+      }
+    });
+
+    document.addEventListener("click", (event) => {
+      if (menuOpen && event.target instanceof Node && !header.contains(event.target)) {
+        setMenu(false);
+      }
+    });
+
+    // Leaving the narrow layout while the menu is open would strand state.
+    window.matchMedia("(min-width: 40.01rem)").addEventListener("change", (event) => {
+      if (event.matches) setMenu(false);
+    });
+
+    root.dataset.header = "shown";
+    update();
+  }
+</script>
+
 <style>
-  .header {
+  .site-header {
+    position: sticky;
+    top: 0;
+    z-index: 50;
+    background: var(--paper);
+    border-bottom: 1px solid transparent;
+    transition:
+      transform 260ms cubic-bezier(0.2, 0.7, 0.2, 1),
+      border-color 200ms ease;
+  }
+
+  .site-header.is-stuck {
+    border-bottom-color: var(--rule);
+  }
+
+  .site-header.is-hidden {
+    transform: translateY(-100%);
+  }
+
+  .site-header__bar {
     display: flex;
     align-items: center;
     justify-content: space-between;
-    min-height: 5rem;
+    min-height: var(--header-height);
   }
 
-  .header__brand {
+  .site-header__brand {
     display: inline-flex;
     align-items: center;
     gap: 0.6rem;
@@ -36,17 +158,17 @@ const links = [
     color: var(--ink);
   }
 
-  .header__brand img {
+  .site-header__brand img {
     display: block;
   }
 
-  .header__nav {
+  .site-header__nav {
     display: flex;
     gap: clamp(1rem, 3vw, 2rem);
     font-size: 0.9375rem;
   }
 
-  .header__nav a {
+  .site-header__nav a {
     padding-block: 0.5rem;
     color: var(--text);
     text-decoration: underline;
@@ -56,8 +178,94 @@ const links = [
     transition: text-decoration-color 150ms ease;
   }
 
-  .header__nav a:hover {
+  .site-header__nav a:hover {
     color: var(--ink);
     text-decoration-color: var(--accent);
   }
+
+  .site-header__toggle {
+    display: none;
+  }
+
+  /* Narrow screens: the links move into a panel under the bar. */
+  @media (max-width: 40rem) {
+    .site-header__toggle {
+      display: inline-flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      gap: 6px;
+      /* 44px square: the minimum comfortable touch target */
+      width: 2.75rem;
+      height: 2.75rem;
+      margin-right: -0.75rem;
+      padding: 0;
+      border: 0;
+      background: transparent;
+      cursor: pointer;
+    }
+
+    .site-header__toggle-bar {
+      display: block;
+      width: 1.375rem;
+      height: 2px;
+      background: var(--ink);
+      transition: transform 200ms ease;
+    }
+
+    .site-header.is-open .site-header__toggle-bar:first-child {
+      transform: translateY(4px) rotate(45deg);
+    }
+
+    .site-header.is-open .site-header__toggle-bar:last-child {
+      transform: translateY(-4px) rotate(-45deg);
+    }
+
+    .site-header__nav {
+      position: absolute;
+      inset-inline: 0;
+      top: 100%;
+      flex-direction: column;
+      gap: 0;
+      padding: 0.5rem var(--gutter) 1.25rem;
+      background: var(--paper);
+      border-bottom: 1px solid var(--rule);
+      font-family: var(--font-display);
+      font-size: 2rem;
+      font-weight: 600;
+      letter-spacing: -0.03em;
+      visibility: hidden;
+      opacity: 0;
+      transform: translateY(-0.5rem);
+      transition:
+        opacity 180ms ease,
+        transform 180ms ease,
+        visibility 0s linear 180ms;
+    }
+
+    .site-header.is-open .site-header__nav {
+      visibility: visible;
+      opacity: 1;
+      transform: none;
+      transition-delay: 0s;
+    }
+
+    .site-header__nav a {
+      padding-block: 0.75rem;
+      color: var(--ink);
+      border-top: 1px solid var(--rule);
+    }
+
+    .site-header__nav a:first-child {
+      border-top: 0;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .site-header,
+    .site-header__nav,
+    .site-header__toggle-bar {
+      transition: none;
+    }
+  }
 </style>
diff --git a/apps/web/src/pages/docs.astro b/apps/web/src/pages/docs.astro
index 45cc4a1..441e0fb 100644
--- a/apps/web/src/pages/docs.astro
+++ b/apps/web/src/pages/docs.astro
@@ -31,6 +31,17 @@ const { Content, headings } = await render(entry);
     padding-block: 1.5rem 5rem;
   }
 
+  /*
+   * Below the grid breakpoint the slot only wraps the mobile contents bar.
+   * Letting its children belong to .docs-page gives that bar the full page
+   * height to stick within; as a box of its own it would never stick.
+   */
+  @media (max-width: 759px) {
+    .docs-sidebar-slot {
+      display: contents;
+    }
+  }
+
   @media (min-width: 760px) {
     .docs-page {
       display: grid;
diff --git a/apps/web/src/styles/docs-prose.css b/apps/web/src/styles/docs-prose.css
index f502354..5bcf95e 100644
--- a/apps/web/src/styles/docs-prose.css
+++ b/apps/web/src/styles/docs-prose.css
@@ -10,7 +10,16 @@
 .docs-prose h4 {
   font-family: var(--font-display);
   color: var(--ink);
-  scroll-margin-top: 2rem;
+}
+
+/* On phones the sticky contents bar also sits under the header. */
+@media (max-width: 759px) {
+  .docs-prose h1,
+  .docs-prose h2,
+  .docs-prose h3,
+  .docs-prose h4 {
+    scroll-margin-top: 4.5rem;
+  }
 }
 
 .docs-prose h1 {
diff --git a/apps/web/src/styles/global.css b/apps/web/src/styles/global.css
index 2dc7299..6cb2e74 100644
--- a/apps/web/src/styles/global.css
+++ b/apps/web/src/styles/global.css
@@ -26,6 +26,9 @@
   --gutter: clamp(1.25rem, 5vw, 4rem);
   --section-space: clamp(4.5rem, 10vw, 8rem);
   --radius: 0.5rem;
+  --header-height: 4.5rem;
+  /* Sticky elements sit below the site header only while it is showing. */
+  --sticky-offset: 0px;
 
   background: var(--paper);
   font-family: var(--font-body);
@@ -42,7 +45,12 @@
 
 html {
   scroll-behavior: smooth;
-  scroll-padding-top: 2rem;
+  /* Anchors land below the site header, which may be showing when they scroll. */
+  scroll-padding-top: calc(var(--header-height) + 1.5rem);
+}
+
+html[data-header="shown"] {
+  --sticky-offset: var(--header-height);
 }
 
 body {