/* ==========================================================================
   guide-article.css
   ONE shared stylesheet for every /guide/*.html page.

   Why this file exists:
   Each of the 22 guide pages currently ships its own <style> block
   (three different token sets, three different class systems: a
   "--gp-*" breadcrumb/hero system, an "--ink/--muted" traffic-light
   system, and a BEM/color-mix system). This file replaces all three
   with one system that extends the tokens already defined in
   /styles.css instead of re-declaring a fourth palette.

   How to use it:
   1. Keep the existing <link rel="stylesheet" href="../styles.css">
   2. Add:  <link rel="stylesheet" href="../guide-article.css">
   3. Delete the page's inline <style> block
   4. Rename that page's markup to the class names below (see the
      migration notes at the bottom of this file)

   Nothing in here touches .guide-layout / .guide-primary / .guide-rail —
   those already live in styles.css and are already consistent across
   every guide, so they're left alone.
   ========================================================================== */

/* --------------------------------------------------------------------------
   1. Tokens — only ADDS what styles.css doesn't already have.
   Layout, ink, action, cyan, paper, card, grid-line, text, mono, sans,
   radius all already exist in :root in styles.css. The only genuinely
   missing pieces are semantic callout colors. --danger below is not a
   new invention — it's the same #c0392b already used by .form-error,
   just promoted to a reusable token.
   -------------------------------------------------------------------------- */
:root {
  --guide-info: var(--action);
  --guide-info-bg: rgba(37, 99, 235, 0.08);
  --guide-success: #1f9d55;
  --guide-success-bg: #e5f6ec;
  --guide-warning: #b5790f;
  --guide-warning-bg: #fbf1de;
  --guide-danger: #c0392b; /* matches .form-error — already the site's error red */
  --guide-danger-bg: #fbe9e7;

  /* Neutral aliases. Introduced when this stylesheet was shared with
     non-Guide UI that consumed these semantic colors for WCAG warnings.
     That consumer has since been removed, but the aliases stay: same
     values, non-Guide names, available to any future non-Guide use. The
     --guide-* originals stay so the existing article rules keep
     working. */
  --ui-info: var(--guide-info);
  --ui-info-bg: var(--guide-info-bg);
  --ui-success: var(--guide-success);
  --ui-success-bg: var(--guide-success-bg);
  --ui-warning: var(--guide-warning);
  --ui-warning-bg: var(--guide-warning-bg);
  --ui-danger: var(--guide-danger);
  --ui-danger-bg: var(--guide-danger-bg);
}

/* Breadcrumb above the hero: Guides / category. The same
   list-with-slashes pattern as .font-breadcrumb (fonts.css) and
   .icons-breadcrumb (icons.css). */
.guide-breadcrumb {
  padding-top: 28px;
}
.guide-breadcrumb ol {
  display: flex;
  flex-wrap: wrap;
  gap: 6px;
  margin: 0;
  padding: 0;
  list-style: none;
  font-size: 13px;
  color: var(--text-muted);
}
.guide-breadcrumb li + li::before {
  content: "/";
  margin-right: 6px;
  color: #9aa2b1;
}
.guide-breadcrumb a {
  text-decoration: none;
}
.guide-breadcrumb a:hover,
.guide-breadcrumb a:focus-visible {
  color: var(--action);
  text-decoration: underline;
  text-underline-offset: 3px;
}

/* --------------------------------------------------------------------------
   2. Hero (eyebrow + title + dek + optional figure)
   Figure reuses the exact blueprint-grid look of .article-hero /
   .card-thumb elsewhere on the site, so a diagram inside a guide reads
   as the same "spec sheet" object as a content-card thumbnail.
   -------------------------------------------------------------------------- */
.guide-hero {
  padding: 28px 0 32px;
  border-bottom: 1px solid var(--grid-line);
  margin-bottom: 36px;
}
/* Plain text, no badge chip — matches .card-meta (styles.css), the same
   "category · level · read time" line the homepage grid and the
   related-guides rail below this article already use. This used to be a
   flex row pairing a bordered/mono .badge with a mono .card-meta span,
   which read as a different, more "tech-spec" style than the rest of
   the site's minimal card meta. */
.guide-hero__meta {
  font-size: 12.5px;
  line-height: 1.4;
  color: var(--text-muted);
  margin-bottom: 14px;
}
.guide-hero__title {
  font-size: clamp(28px, 3.6vw, 40px);
  font-weight: 800;
  letter-spacing: -0.01em;
  line-height: 1.15;
  max-width: 20ch;
  margin: 0 0 14px;
  color: var(--text);
}
.guide-hero__dek {
  font-size: 16px;
  line-height: 1.65;
  color: var(--text-muted);
  max-width: 62ch;
  margin: 0;
}
.guide-hero__figure {
  position: relative;
  aspect-ratio: 20 / 9;
  margin-top: 28px;
  border: 1px solid var(--grid-line);
  border-radius: var(--radius);
  background-color: var(--paper);
  background-image:
    linear-gradient(var(--grid-line) 1px, transparent 1px),
    linear-gradient(90deg, var(--grid-line) 1px, transparent 1px);
  background-size: 18px 18px;
  display: flex;
  align-items: center;
  justify-content: center;
  overflow: hidden;
}
.guide-hero__figure svg {
  width: 46%;
  height: auto;
  color: var(--action);
  overflow: visible;
}

/* --------------------------------------------------------------------------
   3. Table of contents
   -------------------------------------------------------------------------- */
.guide-toc {
  margin: 0 0 44px;
  padding: 20px 24px;
  border: 1px solid var(--grid-line);
  border-radius: var(--radius);
  background: var(--card);
}
/* Structural only, plus this label's own color: pairs with the site's
   existing "section-label mono" utility classes in the markup for
   type, e.g.:
   <span class="section-label mono guide-toc__label">/ on_this_page</span>
   The color override here (rather than on the shared .section-label)
   keeps this blue accent scoped to guide pages — the home page's own
   "/ ALL_GUIDES" label stays plain black, matching its template. */
.guide-toc__label {
  display: block;
  margin-bottom: 12px;
  color: var(--action);
}
.guide-toc ol {
  margin: 0;
  padding-left: 1.25em;
  columns: 2;
  column-gap: 32px;
}
.guide-toc li {
  break-inside: avoid;
  margin-bottom: 8px;
  line-height: 1.4;
  font-size: 14.5px;
}
.guide-toc a {
  color: var(--text);
  text-decoration: none;
}
.guide-toc a:hover,
.guide-toc a:focus-visible {
  color: var(--action);
  text-decoration: underline;
}
@media (max-width: 560px) {
  .guide-toc ol {
    columns: 1;
  }
}

/* --------------------------------------------------------------------------
   4. Prose — headings, paragraphs, lists, code, tables
   -------------------------------------------------------------------------- */
.guide-article {
  max-width: 68ch;
  font-size: 16px;
  line-height: 1.7;
  color: var(--text);
}
.guide-article > * + * {
  margin-top: 24px;
}
.guide-article h2 {
  font-size: 24px;
  font-weight: 800;
  line-height: 1.3;
  color: var(--text);
  margin-top: 56px;
  margin-bottom: 4px;
  scroll-margin-top: 24px;
  letter-spacing: -0.005em;
}
.guide-article h2 .guide-article__num {
  font-family: var(--sans);
  font-weight: 400;
  color: var(--text-muted);
  margin-right: 0.5em;
}
.guide-article h3 {
  font-size: 18px;
  font-weight: 700;
  line-height: 1.35;
  margin-top: 36px;
  margin-bottom: 4px;
  scroll-margin-top: 24px;
}
.guide-article p,
.guide-article li {
  max-width: 62ch;
}
.guide-article ul,
.guide-article ol {
  padding-left: 1.4em;
}
.guide-article li + li {
  margin-top: 8px;
}
.guide-article strong {
  font-weight: 700;
  color: var(--text);
}
.guide-article a {
  color: var(--text);
  text-decoration: underline;
  text-underline-offset: 2px;
  text-decoration-color: var(--grid-line);
}
.guide-article a:hover,
.guide-article a:focus-visible {
  color: var(--action);
  text-decoration-color: currentColor;
}
.guide-article code {
  font-family: var(--sans);
  font-size: 0.875em;
  padding: 0.15em 0.4em;
  border-radius: 2px;
  background: var(--paper);
  border: 1px solid var(--grid-line);
}
.guide-article pre {
  margin-top: 24px;
  padding: 18px 20px;
  overflow-x: auto;
  border: 1px solid var(--header-bg);
  border-radius: var(--radius);
  background: var(--header-bg);
}
.guide-article pre code {
  background: none;
  border: none;
  padding: 0;
  font-size: 0.85em;
  line-height: 1.6;
  color: #e8edf4;
  font-family: var(--sans);
}

.guide-table-wrap {
  margin-top: 24px;
  overflow-x: auto;
  border: 1px solid var(--grid-line);
  border-radius: var(--radius);
}
.guide-article table {
  width: 100%;
  border-collapse: collapse;
  font-size: 14.5px;
  min-width: 480px;
}
.guide-article caption {
  text-align: left;
  padding: 12px 16px 0;
  color: var(--text-muted);
}
.guide-article th,
.guide-article td {
  text-align: left;
  padding: 10px 16px;
  border-bottom: 1px solid var(--grid-line);
  vertical-align: top;
}
.guide-article thead th {
  font-family: var(--sans);
  font-size: 11.5px;
  letter-spacing: 0.04em;
  text-transform: uppercase;
  color: var(--text-muted);
  border-bottom: 1px solid var(--text);
}
.guide-article tbody tr:last-child td {
  border-bottom: none;
}

/* --------------------------------------------------------------------------
   5. Callouts — one component, four semantic variants.
   Replaces the ad hoc "note" boxes each guide invented separately.

   .content-callout is the neutral alias, added for non-Guide UI that
   borrowed this component and had no Guide semantics. That consumer has
   since been removed. Guide articles keep emitting .guide-callout; both
   names resolve to the identical rules below, so appearance is
   unchanged.
   -------------------------------------------------------------------------- */
.content-callout,
.guide-callout {
  padding: 18px 20px;
  border-left: 3px solid var(--guide-info);
  background: var(--guide-info-bg);
  border-radius: 0 var(--radius) var(--radius) 0;
}
.content-callout p,
.guide-callout p {
  margin: 0;
  max-width: none;
}
.content-callout p + p,
.guide-callout p + p {
  margin-top: 10px;
}
.content-callout__label,
.guide-callout__label {
  display: block;
  font-family: var(--sans);
  font-size: 11px;
  letter-spacing: 0.08em;
  text-transform: uppercase;
  margin-bottom: 6px;
  color: var(--text);
}
.content-callout--success,
.guide-callout--success {
  border-left-color: var(--guide-success);
  background: var(--guide-success-bg);
}
.content-callout--warning,
.guide-callout--warning {
  border-left-color: var(--guide-warning);
  background: var(--guide-warning-bg);
}
.content-callout--danger,
.guide-callout--danger {
  border-left-color: var(--guide-danger);
  background: var(--guide-danger-bg);
}

/* --------------------------------------------------------------------------
   6. Example / comparison grid (do vs. don't, before vs. after)
   -------------------------------------------------------------------------- */
.guide-example {
  display: grid;
  gap: 16px;
  grid-template-columns: 1fr;
  margin-top: 24px;
}
@media (min-width: 640px) {
  .guide-example {
    grid-template-columns: 1fr 1fr;
  }
}
.guide-example figure {
  margin: 0;
  padding: 16px;
  border: 1px dashed var(--grid-line);
  border-radius: var(--radius);
}
.guide-example figcaption {
  margin-top: 12px;
  font-size: 13px;
  color: var(--text-muted);
}

/* --------------------------------------------------------------------------
   7. Recap — numbered end-of-section summary
   -------------------------------------------------------------------------- */
.guide-recap {
  margin: 0;
  padding: 0;
  list-style: none;
  display: grid;
  gap: 12px;
}
.guide-recap li {
  display: grid;
  grid-template-columns: auto 1fr;
  gap: 14px;
  padding: 14px 18px;
  background: var(--paper);
  border-left: 3px solid var(--text);
  border-radius: 0 var(--radius) var(--radius) 0;
}
.guide-recap li .guide-recap__n {
  font-family: var(--sans);
  font-size: 13px;
  color: var(--text);
  padding-top: 2px;
}
.guide-recap li p {
  margin: 0;
  font-size: 15px;
  line-height: 1.6;
  color: var(--text);
}
/* Warning variant — for "common pitfalls / mistakes" lists, which are
   structurally identical to a recap (numbered, left-bordered) but read
   as cautionary rather than a neutral summary. Reuses the same warning
   tokens --guide-warning / --guide-warning-bg already defined for
   .guide-callout--warning above, so the two "this is a warning" looks
   stay visually consistent wherever they appear. */
.guide-recap--warning li {
  background: var(--guide-warning-bg);
  border-left-color: var(--guide-warning);
}
.guide-recap--warning li .guide-recap__n {
  color: var(--text);
}

/* --------------------------------------------------------------------------
   8. CTA — reuses the site's real .btn-primary instead of a bespoke button
   -------------------------------------------------------------------------- */
.guide-cta {
  margin-top: 64px;
  padding: 28px;
  border: 1px solid var(--grid-line);
  border-radius: var(--radius);
  background: var(--card);
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  justify-content: space-between;
  gap: 16px;
}
.guide-cta__text strong {
  display: block;
  font-size: 16px;
  color: var(--text);
  margin-bottom: 4px;
}
.guide-cta__text span {
  font-size: 14px;
  color: var(--text-muted);
}

/* --------------------------------------------------------------------------
   9. Diagram — dark-frame technical illustration, for mid-article figures
   (as opposed to .guide-hero__figure, which is the lead image up top).
   These are hand-authored, multi-color inline SVGs (accent lines, state
   comparisons, etc.) with colors baked into the markup on purpose — the
   goal here is only to give them a consistent frame, not to repaint each
   guide's bespoke illustration into a single accent color. Mirrors
   .guide-article pre's existing dark treatment below so code blocks and
   diagrams read as the same family of "technical content" chrome.
   -------------------------------------------------------------------------- */
.guide-diagram {
  max-width: 100%;
  margin: 32px 0;
}
.guide-diagram__frame {
  background: var(--header-bg);
  border: 1px solid var(--header-bg);
  border-radius: var(--radius);
  padding: 18px 18px 14px;
}
.guide-diagram__frame svg {
  display: block;
  width: 100%;
  height: auto;
}
.guide-diagram figcaption {
  font-family: var(--sans);
  font-size: 12px;
  letter-spacing: 0.02em;
  color: var(--text-muted);
  margin-top: 10px;
}
/* Light variant — for diagrams drawn with the constrained semantic
   palette (ink / success / warning / danger) rather than Family A's
   free-color illustrations. Those already read fine on a light card;
   forcing them into the dark frame above would fight their own colors
   instead of just framing them. */
.guide-diagram--light .guide-diagram__frame {
  background: var(--card);
  border: 1px solid var(--grid-line);
}
.guide-diagram--light .guide-diagram__frame svg {
  width: auto;
  max-width: 100%;
  margin: 0 auto;
}
/* Legend row of color-coded chips underneath a diagram (e.g. a
   green/amber/red reachability map). Reuses the exact callout tokens
   above so "this chip means the same thing as that callout" stays true
   wherever the two appear on the same page. */
.guide-diagram__legend {
  display: flex;
  flex-wrap: wrap;
  justify-content: center;
  gap: 8px;
  margin: 14px 0 4px;
}
.guide-diagram__chip {
  font-family: var(--sans);
  font-size: 11px;
  letter-spacing: 0.04em;
  border-radius: 4px;
  padding: 4px 9px;
  border: 1px solid transparent;
  color: var(--text);
  background: var(--guide-info-bg);
}
.guide-diagram__chip--success {
  color: var(--text);
  background: var(--guide-success-bg);
}
.guide-diagram__chip--warning {
  color: var(--text);
  background: var(--guide-warning-bg);
}
.guide-diagram__chip--danger {
  color: var(--text);
  background: var(--guide-danger-bg);
}

/* --------------------------------------------------------------------------
   10. Footer nav — sequential prev/next between guides (roadmap order),
   distinct from .guide-rail's topic-related suggestions below the article.
   -------------------------------------------------------------------------- */
.guide-footer-nav {
  display: flex;
  justify-content: space-between;
  gap: 16px;
  flex-wrap: wrap;
  border-top: 1px solid var(--grid-line);
  padding-top: 24px;
  margin-top: 44px;
  font-size: 14px;
}
.guide-footer-nav a {
  color: var(--text);
  text-decoration: none;
  max-width: 32ch;
}
.guide-footer-nav a:hover,
.guide-footer-nav a:focus-visible {
  color: var(--action);
  text-decoration: underline;
}
.guide-footer-nav .next {
  text-align: right;
  margin-left: auto;
}
@media (max-width: 560px) {
  .guide-footer-nav {
    flex-direction: column;
  }
  .guide-footer-nav .next {
    text-align: left;
    margin-left: 0;
  }
}

/* --------------------------------------------------------------------------
   11. Spec sheet — a bordered term/value reference box (e.g. a "the spec"
   closing section), distinct from .guide-callout (a note, not a lookup
   table) and .guide-recap (a numbered list, not term/value pairs).
   -------------------------------------------------------------------------- */
.guide-spec {
  border: 1px solid var(--grid-line);
  border-radius: var(--radius);
  padding: 24px 26px;
  margin: 30px 0;
  background: var(--card);
}
.guide-spec__label {
  font-family: var(--sans);
  font-size: 12px;
  letter-spacing: 0.08em;
  color: var(--text);
  margin: 0 0 14px;
}
.guide-spec dl {
  display: grid;
  grid-template-columns: max-content 1fr;
  gap: 8px 18px;
  margin: 0;
}
.guide-spec dt {
  font-family: var(--sans);
  font-size: 13px;
  color: var(--text-muted);
  white-space: nowrap;
}
.guide-spec dd {
  margin: 0;
  font-size: 14.5px;
  color: var(--text);
}

/* --------------------------------------------------------------------------
   12. Save — the bookmark at the end of the hero's meta line, drawn by
   /app.js (src/client/guides.js, initGuideSave) only once account Saved is
   launched (docs/SAVED.md), so nothing here matches before then. The
   bookmark and its states are the ones /palettes and /colors use: muted,
   the action blue on hover or focus and when saved (filled), dimmed while
   aria-busy, at least 24px square. The negative block margins keep that
   target from growing the 17.5px meta line, so drawing it never moves the
   title below.
   -------------------------------------------------------------------------- */
.guide-save-btn {
  appearance: none;
  background: none;
  border: 0;
  display: inline-flex;
  align-items: center;
  justify-content: center;
  vertical-align: middle;
  min-width: 24px;
  min-height: 24px;
  padding: 2px 3px;
  margin: -4px 0 -4px 6px;
  cursor: pointer;
  color: var(--text-muted);
  transition:
    color 0.16s cubic-bezier(0.2, 0.6, 0.3, 1),
    opacity 0.16s cubic-bezier(0.2, 0.6, 0.3, 1);
}
.guide-save-btn svg {
  width: 16px;
  height: 16px;
  transition:
    transform 0.16s cubic-bezier(0.2, 0.6, 0.3, 1),
    fill 0.16s cubic-bezier(0.2, 0.6, 0.3, 1);
}
/* Hover guarded on a fine pointer: a tap would otherwise leave an unsaved
   bookmark blue until the next tap elsewhere. */
@media (hover: hover) and (pointer: fine) {
  .guide-save-btn:hover {
    color: var(--action);
  }
  .guide-save-btn:hover svg {
    transform: scale(1.08);
  }
}
.guide-save-btn:focus-visible {
  color: var(--action);
}
.guide-save-btn:active svg {
  transform: scale(0.9);
}
/* Saved: filled in the action blue, hovered or not. */
.guide-save-btn[aria-pressed="true"] {
  color: var(--action);
}
.guide-save-btn[aria-pressed="true"] svg {
  fill: currentColor;
}
.guide-save-btn[aria-busy="true"] {
  cursor: progress;
  opacity: 0.55;
}
/* styles.css already shortens every transition; the scale is switched off
   outright, as /palettes and /colors do. */
@media (prefers-reduced-motion: reduce) {
  .guide-save-btn:hover svg,
  .guide-save-btn:active svg {
    transform: none;
  }
}