/*
 * Utilities — the curated, token-driven vocabulary shared with verkilo.com.
 *
 * CUBE's U: each class is one intent, configured through custom properties
 * with token defaults. Names match the marketing site's utilities layer so the
 * two properties read as one system; only the measures differ (docs works to
 * `ch` measures rather than the marketing site's rem columns).
 *
 * Utilities is the last layer, so a utility always wins over a block.
 */
@layer utilities {
  /* ── Type ──────────────────────────────────────────────────────────── */
  .font-display { font-family: var(--font-display); font-weight: 400; }
  .text-muted { color: var(--ink-muted); }
  .text-subtle { color: var(--ink-subtle); }
  .text-accent { color: var(--accent); }
  .text-spot { color: var(--accent-spot); }
  .text-balance { text-wrap: balance; }
  .text-pretty { text-wrap: pretty; }
  .text-center { text-align: center; }
  .text-end { text-align: end; }

  /* Microcaps — small letterspaced monospace caps. The utility voice of the
     redesign: kickers, breadcrumbs, meta rails, table headers, tree labels. */
  .microcaps {
    font-family: var(--font-mono);
    font-size: var(--microcaps-size, var(--text-micro));
    font-weight: 500;
    letter-spacing: var(--microcaps-tracking, var(--tracking-caps));
    text-transform: uppercase;
  }
  /* Looser tracking reads better on sentence-length strings (meta rails,
     breadcrumbs) than on two-word labels. */
  .microcaps-loose { --microcaps-tracking: var(--tracking-caps-loose); }

  /* Numeral — the small mono copper index number beside a doc-tree entry or a
     start-here row. (The large Solway numeral is the .docs-numeral block.) */
  .numeral-mono {
    color: var(--accent-spot);
    font-family: var(--font-mono);
    font-size: var(--text-micro);
    font-weight: 500;
  }

  /* Caption — monospace plate/figure caption, sentence case. */
  .caption {
    color: var(--ink-subtle);
    font-family: var(--font-mono);
    font-size: var(--text-x-small);
    letter-spacing: var(--tracking-caption);
  }

  /* ── Measures — line length named by intent. ───────────────────────── */
  .measure-prose { max-inline-size: var(--measure-docs-prose); }
  .measure-lede { max-inline-size: var(--measure-docs-lede); }
  .measure-lede-mid { max-inline-size: var(--measure-docs-lede-mid); }
  .measure-lede-short { max-inline-size: var(--measure-docs-lede-short); }
  .measure-blurb { max-inline-size: var(--measure-docs-blurb); }
  .measure-note { max-inline-size: var(--measure-docs-note); }

  /* ── Rules ─────────────────────────────────────────────────────────── */
  /* Spot rule — the short copper divider under a page head (96x3) or an
     article h2 (56x2). Tune with the two knobs; the block sets neither. */
  .rule-spot {
    background: var(--accent-spot);
    block-size: var(--rule-spot-size, var(--rule-width));
    border: 0;
    inline-size: var(--rule-spot-length, var(--rule-length));
    margin-inline: var(--rule-spot-inline, 0);
  }
  .rule-spot-short { --rule-spot-size: var(--spine-width); --rule-spot-length: var(--rule-length-short); }

  /* Ruled bands — a hairline above/below a block, with breathing room. */
  .rule-above { border-block-start: 1px solid var(--line); padding-block-start: var(--space-sm); }
  .rule-below { border-block-end: 1px solid var(--line); padding-block-end: var(--space-sm); }

  /* ── Layout helpers ────────────────────────────────────────────────── */
  .grow { flex: 1; }

  /* Sticky rail — pins below the sticky masthead and rides along. Anything
     sticky on this site offsets by the masthead height, so the offset reads
     from the same token the masthead is sized with. */
  .sticky-top {
    align-self: start;
    inset-block-start: var(--sticky-offset, var(--docs-header));
    position: sticky;
  }
  @media (max-width: 48em) /* --breakpoint-md */ {
    .sticky-top { position: static; }
  }

  /* Visually hidden — available to screen readers, off-screen for everyone
     else. Used by icon-only controls and the skip link before focus. */
  .visually-hidden {
    block-size: 1px;
    clip-path: inset(50%);
    inline-size: 1px;
    overflow: hidden;
    position: absolute;
    white-space: nowrap;
  }

  /* ── Theme-paired screenshots ──────────────────────────────────────── */
  /* Expose the [data-mode="dark"] image and hide the light one when dark is
     active (explicit choice or system preference). In the utilities layer so
     no block's own display rule can un-hide the inactive image. */
  [data-mode="dark"] { display: none; }
  html[data-theme="dark"] [data-mode="light"] { display: none; }
  html[data-theme="dark"] [data-mode="dark"] { display: block; }
  @media (prefers-color-scheme: dark) {
    html:not([data-theme]) [data-mode="light"] { display: none; }
    html:not([data-theme]) [data-mode="dark"] { display: block; }
  }
}