nav.css

/* The two navigation tiers, owned by the layout.
 *
 * These rules used to live inside brand-kit.astro's <style>, next to a comment
 * saying `.ds-nav-stack` "is this page's arrangement and no other page has it".
 * That was true when one page had a second bar. It stopped being true when the
 * site collapsed to two surfaces, one of which is a single long page that
 * cannot be navigated without one -- so the arrangement moved here, and DocPage
 * links this file on every page rather than each page restating it.
 *
 * The stack is what makes the two bars behave as one block. Without it they
 * race for the same top edge: both want to be sticky, so the second scrolls
 * under the first. Sticking the WRAPPER and leaving both children static means
 * neither needs to know the other's height -- which is the bug this replaced,
 * where the sub-bar carried `top: var(--ds-nav-height)` and drifted whenever
 * the main bar's padding changed. Nothing here depends on a measured number.
 */

.ds-nav-stack {
  position: sticky;
  top: 0;
  z-index: 20;
}

/* --- the second tier ------------------------------------------------------ */

.ds-subnav {
  /* Placed by the stack above, not by an offset of its own. */
  position: static;
  border-bottom: 1px solid var(--color-surface-quaternary);
  background: var(--color-surface-primary-transparent);
  -webkit-backdrop-filter: blur(24px);
  backdrop-filter: blur(24px);
}

.ds-subnav-inner {
  box-sizing: border-box; /* the site resets this globally; these pages do not */
  display: flex;
  /* The wordmark belongs to the global bar directly above, so this row has
     nothing to split around -- the links close up and read as one centred row. */
  justify-content: center;
  align-items: center;
  gap: 0.25rem;
  position: relative;
  min-height: 0; /* .page-container's 100% floor is for pages, not bars */
  padding-top: 0.75rem;
  padding-bottom: 0.75rem;
}

.ds-subnav ul {
  display: flex;
  flex-wrap: wrap;
  justify-content: center;
  gap: 0.25rem;
  margin: 0;
  padding: 0;
  list-style: none;
}

/* The current section, marked the same way BrandNav marks the current item:
   by weight and foreground, never by a box that shifts the row's height. */
.ds-subnav a[aria-current='true'] {
  color: var(--color-heading);
  font-weight: var(--font-weight-bold);
}

/* Anchor jumps have to clear BOTH bars, so any element a sub-nav link targets
   carries this rather than the pages guessing an offset each.
 *
 * This used to be a flat `9rem`, which is the one thing in this file the header
 * above promises is not here: a measured number. It was 144px against a stack
 * that measures 146, so it was always 2px short — invisible, and therefore
 * never fixed. Adding a seventh item to the kitchen sink's sub-nav made it
 * visible: the bar wrapped to two rows, the stack became 198px, and the heading
 * landed 54px underneath it.
 *
 * So it is derived now. Both tiers are the same construction — a
 * --control-height control with 0.75rem of padding above and below and a 1px
 * rule under it — which is why one name describes both.
 */
:root {
  --ds-bar: calc(var(--control-height) + 1.5rem + 1px);
  /* A sub-nav that wraps adds one more control, plus the row gap. */
  --ds-bar-wrapped-row: calc(var(--control-height) + 0.25rem);
}

.ds-anchor {
  /* Two bars, and a sub-nav wrapped to two rows.
   *
   * Two rows is the worst case wherever this matters, and provably rather than
   * hopefully: the widest sub-nav measures 986px laid out on one row, so it
   * cannot need a third until about 493px — well below the 767px where the
   * stack stops being sticky at all and this offset stops applying.
   *
   * On a wide screen the sub-nav is one row and this over-clears by ~52px.
   * That is the right direction to be wrong in: over-clearing is breathing
   * room under a sticky bar, under-clearing hides the heading being linked to. */
  scroll-margin-top: calc(2 * var(--ds-bar) + var(--ds-bar-wrapped-row));
}

@media (max-width: 768px) {
  .ds-subnav-inner {
    overflow-x: auto;
    justify-content: flex-start;
    -webkit-overflow-scrolling: touch;
  }

  .ds-subnav ul {
    flex-wrap: nowrap;
    width: max-content;
    min-width: 100%;
  }

  .ds-subnav a {
    white-space: nowrap;
  }
}