/* ==========================================================================
   Docs pages (/docs, /docs/*) - layout + prose styles for the generated
   documentation site. Loaded AFTER analyser.css, so all theme tokens
   (--bg, --fg, --muted, --surface, --hairline, --accent, --font-mono, ...)
   and the global header/footer classes come from there. This file only adds
   what the docs need: the sidebar + article layout and markdown prose.
   Generated pages are built by tools/build-docs-html.mjs from docs/*.md.
   Same rules as everywhere else on the site: sharp corners, hairlines,
   tokens over hardcoded values.
   ========================================================================== */

/* Docs-only tokens. docs.css loads only on /docs pages, so this :root addition
   is scoped to them. --docs-topbar-h coordinates the sticky top bar's height
   with the sidebar's sticky offset and the heading scroll-margin. */
:root { --docs-topbar-h: 52px; }

/* ----- Top bar: pinned to the top of the viewport, mono chrome (not the big
   hero header the app pages use - docs pages want content near the top). ----- */

.docs-topbar {
  position: sticky;
  top: 0;
  z-index: 30;
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: var(--gap);
  flex-wrap: wrap;
  max-width: 1440px;
  margin: 0 auto;
  padding: 12px var(--pad-x);
  background: var(--surface);
  border-bottom: var(--bd-hairline);
}
.docs-brand {
  font-family: var(--font-mono);
  font-size: var(--t-small);
  text-transform: uppercase;
  letter-spacing: 0.08em;
  display: flex;
  align-items: center;
  gap: 8px;
}
.docs-brand a { text-decoration: none; }
.docs-brand-mark { color: var(--fg); font-weight: 700; }
.docs-brand-mark:hover { color: var(--accent); }
.docs-brand-sep { color: var(--muted); }
.docs-brand-docs { color: var(--muted); }
.docs-topnav {
  display: flex;
  align-items: center;
  gap: 8px;
  flex-wrap: wrap;
}
/* Every chip in the bar - the Home/About/Formats links and the day/night
   toggle - shares one identical box so they line up at exactly the same
   height (the site's .dark-toggle otherwise renders a touch taller). The
   topbar itself is a surfaced band, so the chips drop to the page background
   (with their hairline border) to read as crisp buttons against it. :not(:hover)
   on the background, not a bare selector - .header-btn:hover / .dark-toggle:hover
   in analyser.css tie this selector's specificity, and docs.css loads after, so
   an unconditional background here would always win and swallow the hover fill. */
.docs-topnav .header-btn,
.docs-topnav .dark-toggle {
  height: 26px;
  padding: 0 10px;
  display: inline-flex;
  align-items: center;
  line-height: 1;
}
.docs-topnav .header-btn:not(:hover),
.docs-topnav .dark-toggle:not(:hover) {
  background: var(--bg);
}

.docs-shell {
  display: grid;
  grid-template-columns: 232px minmax(0, 1fr);
  gap: calc(var(--gap) * 2);
  padding: clamp(28px, 4vw, 48px) var(--pad-x) clamp(48px, 6vw, 80px);
  max-width: 1440px;
  margin: 0 auto;
  width: 100%;
}

/* ----- Sidebar ----- */

/* The sidebar is a surfaced card (like the content sections), not bare text on
   the grid - a panel with the --surface fill, a hairline border and sharp
   corners, kept sticky below the pinned top bar. */
.docs-side {
  position: sticky;
  top: calc(var(--docs-topbar-h) + 20px);
  align-self: start;
  max-height: calc(100vh - var(--docs-topbar-h) - 40px);
  overflow-y: auto;
  font-family: var(--font-mono);
  font-size: var(--t-small);
  background: var(--surface);
  border: var(--bd-hairline);
  padding: 16px 14px;
  scrollbar-width: thin;
}

.docs-filter {
  width: 100%;
  font-family: var(--font-mono);
  font-size: var(--t-small);
  color: var(--fg);
  background: var(--bg);
  border: var(--bd-hairline);
  border-radius: 0;
  padding: 6px 8px;
  margin-bottom: 18px;
}
.docs-filter:focus { outline: 2px solid var(--accent); outline-offset: -1px; }
.docs-filter::placeholder { color: var(--muted); }

.docs-nav-group { margin-bottom: 18px; }
.docs-nav-label {
  display: block;
  font-size: var(--t-tiny);
  text-transform: uppercase;
  letter-spacing: 0.08em;
  color: var(--muted);
  margin-bottom: 6px;
}
.docs-nav a {
  display: block;
  color: var(--fg);
  text-decoration: none;
  padding: 3px 6px;
  margin-left: -6px;
  line-height: 1.4;
}
.docs-nav a:hover { color: var(--accent); }
.docs-nav a[aria-current="page"] {
  background: var(--fg);
  color: var(--bg);
  cursor: default;
}
.docs-nav a.is-filtered-out { display: none; }
.docs-nav-group.is-filtered-out { display: none; }

/* Mobile drop-down clone of the sidebar (the sticky rail is hidden there). */
.docs-mobile-nav { display: none; }

/* ----- Article prose ----- */

.docs-article { min-width: 0; }

/* Page header: the doc title + lede, sitting on the page (not carded). */
.docs-head { margin: 0 0 var(--gap); }
.docs-head h1 {
  font-size: clamp(28px, 3.4vw, 42px);
  font-weight: 800;
  letter-spacing: -0.02em;
  line-height: 1.1;
  margin: 0 0 10px;
}
.docs-lede {
  color: var(--muted);
  max-width: 70ch;
  margin: 0;
}

/* ----- Section cards: each doc section sits on a surfaced, hairline-bordered
   card (the site's --surface token) so blocks of text read as distinct,
   scannable panels floating on the grid - sharp corners, like everything
   else. ----- */
.docs-card {
  background: var(--surface);
  border: var(--bd-hairline);
  padding: clamp(20px, 2.4vw, 30px) clamp(20px, 2.6vw, 34px);
  margin: 0 0 var(--gap);
  scroll-margin-top: calc(var(--docs-topbar-h) + 16px);
}
.docs-card > :first-child { margin-top: 0; }
.docs-card > :last-child { margin-bottom: 0; }

.docs-article h2 {
  font-size: 21px;
  font-weight: 800;
  letter-spacing: -0.01em;
  margin: 44px 0 12px;
  padding-top: 22px;
  border-top: var(--bd-hairline);
}
.docs-article h3 {
  font-size: 16px;
  font-weight: 700;
  margin: 30px 0 8px;
}
.docs-article h4 {
  font-size: 14px;
  font-weight: 700;
  margin: 22px 0 6px;
}
/* The heading that opens a card is that card's title: no top divider (the card
   border already separates it), a hairline underline beneath it instead. */
.docs-card > h2:first-child,
.docs-card > h3:first-child {
  margin: 0 0 16px;
  padding: 0 0 10px;
  border-top: none;
  border-bottom: var(--bd-hairline);
}
/* Anchor scroll targets clear the pinned top bar. */
.docs-article :is(h2, h3, h4) { scroll-margin-top: calc(var(--docs-topbar-h) + 16px); }
/* Inside a surfaced card, code/pre would vanish on the same fill - drop them to
   the page background so they read as insets. */
.docs-card code { background: var(--bg); }
.docs-card pre { background: var(--bg); }
.docs-card pre code { background: none; }

/* Hover anchors on headings - same quiet treatment as muted chrome. */
.docs-article h2, .docs-article h3, .docs-article h4 { position: relative; }
.h-anchor {
  font-family: var(--font-mono);
  font-weight: 400;
  font-size: 0.8em;
  color: var(--muted);
  text-decoration: none;
  margin-left: 8px;
  opacity: 0;
}
h2:hover .h-anchor, h3:hover .h-anchor, h4:hover .h-anchor { opacity: 1; }
.h-anchor:hover { color: var(--accent); }

.docs-article p,
.docs-article li {
  line-height: 1.6;
  max-width: 78ch;
}
.docs-article p { margin: 0 0 14px; }
.docs-article ul, .docs-article ol { margin: 0 0 14px; padding-left: 22px; }
.docs-article li { margin: 0 0 6px; }
.docs-article li > ul, .docs-article li > ol { margin: 6px 0 0; }

.docs-article code {
  font-family: var(--font-mono);
  font-size: 0.88em;
  background: var(--surface);
  border: var(--bd-hairline);
  border-radius: 0;
  padding: 1px 5px;
  white-space: nowrap;
}
.docs-article a code { color: inherit; }
.docs-article pre {
  background: var(--surface);
  border: var(--bd-hairline);
  padding: 14px 16px;
  overflow-x: auto;
  margin: 0 0 16px;
  max-width: 100%;
}
.docs-article pre code {
  background: none;
  border: 0;
  padding: 0;
  white-space: pre;
  font-size: var(--t-small);
  line-height: 1.5;
}

/* ----- Live component demos (```demo fences) -----
   A framed strip that renders the site's real UI elements (.anr-btn, .anr-card,
   .anr-palette, ... - all styled in analyser.css) inline in the prose. The strip
   is an inset: a hairline box dropping to the page background, matching how code
   insets read inside a --surface docs card. Sharp corners, tokens only. */
.docs-demo {
  border: var(--bd-hairline);
  background: var(--bg);
  margin: 0 0 18px;
  max-width: 100%;
}
.docs-demo-stage { padding: 16px 18px; text-align: center; }
.docs-demo-stage > :first-child { margin-top: 0; }
.docs-demo-stage > :last-child { margin-bottom: 0; }
/* Reset the in-app spacing the components carry for their live-page context so
   they sit tidily stacked in the demo strip, and centre each element within it. */
.docs-demo-stage .anr-btn-row { margin: 0; justify-content: center; }
.docs-demo-stage .anr-btn-row + .anr-btn-row,
.docs-demo-stage .anr-btn-row + .anr-palette,
.docs-demo-stage .anr-palette + .anr-btn-row { margin-top: 10px; }
.docs-demo-stage .anr-card { margin: 0; }
.docs-demo-stage .anr-card + .anr-card { margin-top: 22px; }
/* A card's body controls need a touch of air below its underlined heading; the
   heading is a flex row, so centre it explicitly (text-align won't reach it). */
.docs-demo-stage .anr-card > h3 { margin-bottom: 12px; justify-content: center; }
.docs-demo-stage .anr-card p { margin: 0 0 12px; }
/* On the live page the palette is a fixed repeat(8, 1fr) grid always filled
   with 8 dominant colours; in a demo the count varies (7 theme tokens, etc.),
   and an under-filled grid track leaves a stray empty cell (just its top border
   line). Lay the demo swatches out with flex instead - only the swatches that
   exist are drawn - and give them a fixed, roomy size so their hex/token
   labels fit without truncation. */
.docs-demo-stage .anr-palette {
  display: flex;
  flex-wrap: wrap;
  width: -moz-fit-content;
  width: fit-content;
  max-width: 100%;
  margin-left: auto;
  margin-right: auto;
}
.docs-demo-stage .anr-swatch { width: 84px; }
/* Press feedback: the demo buttons invert on click/tap the same way the live
   controls invert on hover, so they feel interactive (docs.js adds the
   toggle/segmented latching on top - visual only, no real functionality). */
.docs-demo-stage .anr-btn:active { background: var(--fg); color: var(--bg); border-color: var(--fg); }
.docs-demo-stage .anr-btn--cta:active { background: var(--accent); color: var(--accent-fg); border-color: var(--accent); filter: brightness(1.1); }

.docs-article table {
  border-collapse: collapse;
  width: 100%;
  margin: 0 0 18px;
  font-size: var(--t-small);
}
.docs-article th {
  font-family: var(--font-mono);
  font-size: var(--t-tiny);
  text-transform: uppercase;
  letter-spacing: 0.08em;
  color: var(--muted);
  font-weight: 500;
  text-align: left;
  padding: 6px 12px 6px 0;
  border-bottom: 1px solid var(--fg);
}
.docs-article td {
  padding: 8px 12px 8px 0;
  border-bottom: var(--bd-hairline);
  vertical-align: top;
  line-height: 1.55;
}
.docs-article td:last-child, .docs-article th:last-child { padding-right: 0; }
/* Wide reference tables scroll sideways instead of breaking the column. */
.docs-table-wrap { overflow-x: auto; margin: 0 0 18px; }
.docs-table-wrap table { margin: 0; }

/* "On this page" table of contents */
.docs-toc {
  background: var(--surface);
  border: var(--bd-hairline);
  margin: 18px 0 26px;
  font-family: var(--font-mono);
  font-size: var(--t-small);
  /* Shrink to content: collapsed it's a compact "On this page" button, and only
     grows to fit its links when opened (never the full column width). */
  width: -moz-fit-content;
  width: fit-content;
  max-width: 78ch;
}
.docs-toc summary {
  cursor: pointer;
  padding: 8px 12px;
  font-size: var(--t-tiny);
  text-transform: uppercase;
  letter-spacing: 0.08em;
  text-align: center;
  color: var(--muted);
  list-style: none;
  -webkit-user-select: none;
  user-select: none;
}
.docs-toc summary::-webkit-details-marker { display: none; }
.docs-toc summary::after { content: ' \25BE'; }
.docs-toc[open] summary { border-bottom: var(--bd-hairline); }
.docs-toc ul { list-style: none; margin: 0; padding: 10px 12px; }
.docs-toc li { margin: 0 0 4px; }
.docs-toc li.toc-h3 { padding-left: 16px; }
.docs-toc a { color: var(--fg); text-decoration: none; }
.docs-toc a:hover { color: var(--accent); }

/* ----- Previous / next pager ----- */

.docs-pn {
  display: grid;
  grid-template-columns: 1fr 1fr;
  gap: var(--gap);
  margin-top: 48px;
  padding-top: 24px;
  border-top: var(--bd-hairline);
}
.docs-pn a {
  display: block;
  background: var(--surface);
  border: var(--bd-hairline);
  padding: 12px 14px;
  text-decoration: none;
  color: var(--fg);
}
.docs-pn a:hover { background: var(--fg); color: var(--bg); }
.docs-pn a:hover .docs-pn-dir { color: inherit; }
.docs-pn-next { text-align: right; grid-column: 2; }
.docs-pn-dir {
  display: block;
  font-family: var(--font-mono);
  font-size: var(--t-tiny);
  text-transform: uppercase;
  letter-spacing: 0.08em;
  color: var(--muted);
  margin-bottom: 4px;
}
.docs-pn-title { font-weight: 700; }

/* The footer is the shared site footer (.site-footer, styled in analyser.css) -
   same as every other page - so nothing is styled for it here. */

/* ----- Narrow screens ----- */

@media (max-width: 900px) {
  /* minmax(0, 1fr) - not plain 1fr - so a long unbreakable token (nowrap inline
     code, a wide table) can't force the column past the viewport width. */
  .docs-shell { grid-template-columns: minmax(0, 1fr); gap: var(--gap); }
  .docs-side { display: none; }
  .docs-mobile-nav {
    display: block;
    background: var(--surface);
    border: var(--bd-hairline);
    font-family: var(--font-mono);
    font-size: var(--t-small);
  }
  .docs-mobile-nav > summary {
    cursor: pointer;
    padding: 10px 12px;
    font-size: var(--t-tiny);
    text-transform: uppercase;
    letter-spacing: 0.08em;
    color: var(--muted);
    list-style: none;
    -webkit-user-select: none;
    user-select: none;
  }
  .docs-mobile-nav > summary::-webkit-details-marker { display: none; }
  .docs-mobile-nav > summary::after { content: ' \25BE'; }
  .docs-mobile-nav[open] > summary { border-bottom: var(--bd-hairline); }
  .docs-mobile-nav .docs-nav { padding: 12px; }
  .docs-pn { grid-template-columns: 1fr; }
  .docs-pn-next { grid-column: auto; }
}