.with-baseline-grid {
  /* Baseline unit — 4px, SHIMMED here in the debug tool.
   *
   * The real --baseline-height comes from the typography engine, which derives
   * it from the design-tokens repo (--dimension-size-height-baseline), currently
   * still 8px there. The debug overlay must not inherit that stale 8px, and it
   * cannot depend on @canonical/styles' 4px override having loaded first (the
   * addon may load this CSS in isolation). So the tool owns its own default:
   *   1. --baseline-grid-height — explicit override for this tool (wins), else
   *   2. 0.25rem (4px) — the shimmed default, NOT read from --baseline-height.
   * To pin the overlay to whatever the app's live grid is, a consumer sets
   * --baseline-grid-height: var(--baseline-height) explicitly. */
  --addon-baseline-height: var(--baseline-grid-height, 0.25rem);

  /* Overlay reads as STRICT BANDS — five hard-edged baseline-height steps per
   * cycle, each a step up in tint (not a smooth gradient). One cycle is 5
   * baselines, then repeats. Hard edges between bands let the eye count
   * position-within-cycle (level 1..5) exactly; the strongest band marks the
   * cycle. Tint derives from one branded hue at stepped opacities.
   *
   * The cycle is FIXED at 5 levels: the tint stops below (--addon-baseline-l1..l5)
   * are hard-coded, so the count is not a knob — a different value would leave the
   * five stops crammed into a mis-sized cycle. Only the baseline HEIGHT is
   * customisable (--baseline-grid-height); the level count is intrinsic. */
  --addon-baseline-cycle: calc(
    var(--addon-baseline-height) *
    5
  ); /* 5 baselines per cycle */

  --addon-baseline-hue: var(
    --baseline-grid-color,
    var(--color-border-branded, oklch(64.05% 0.1941 37.76))
  );
  /* Five stepped tints, faint (level 1) → strong (level 5). Hard steps. */
  --addon-baseline-l1: color-mix(
    in oklch,
    var(--addon-baseline-hue) 8%,
    transparent
  );
  --addon-baseline-l2: color-mix(
    in oklch,
    var(--addon-baseline-hue) 14%,
    transparent
  );
  --addon-baseline-l3: color-mix(
    in oklch,
    var(--addon-baseline-hue) 20%,
    transparent
  );
  --addon-baseline-l4: color-mix(
    in oklch,
    var(--addon-baseline-hue) 28%,
    transparent
  );
  --addon-baseline-l5: color-mix(
    in oklch,
    var(--addon-baseline-hue) 38%,
    transparent
  );

  --addon-baseline-shift: var(--baseline-shift, 0);

  position: relative;

  /*
   * The grid is an ::after overlay (kept so it paints ON TOP and can cover the
   * full page, not just behind content). To survive content TALLER than 100%
   * (overflowing children), the pseudo grows with the host: min-block-size:100%
   * fills the box.
   *
   * One gradient, but with hard stops so it renders as five STRICT bands: each
   * `color N, color N+1baseline` pair is a flat 4px step with no interpolation,
   * and the next step starts exactly where the previous ends. 5 steps = a 20px
   * cycle, repeated.
   */
  &::after {
    content: "";
    display: block;
    position: absolute;
    inset: 0;
    block-size: 100%;
    min-block-size: 100%;
    pointer-events: none;
    z-index: 200;
    background-image: linear-gradient(
      to bottom,
      var(--addon-baseline-l1) 0,
      var(--addon-baseline-l1) var(--addon-baseline-height),
      var(--addon-baseline-l2) var(--addon-baseline-height),
      var(--addon-baseline-l2) calc(var(--addon-baseline-height) * 2),
      var(--addon-baseline-l3) calc(var(--addon-baseline-height) * 2),
      var(--addon-baseline-l3) calc(var(--addon-baseline-height) * 3),
      var(--addon-baseline-l4) calc(var(--addon-baseline-height) * 3),
      var(--addon-baseline-l4) calc(var(--addon-baseline-height) * 4),
      var(--addon-baseline-l5) calc(var(--addon-baseline-height) * 4),
      var(--addon-baseline-l5) var(--addon-baseline-cycle)
    );
    background-size: 100% var(--addon-baseline-cycle);
    background-position: 0 var(--addon-baseline-shift);
    background-repeat: repeat;
  }
}