From 8b08c82aeb1f356d5dd25224bb7b8872f07ab8f5 Mon Sep 17 00:00:00 2001
From: Eleanor Frajka-Williams <eleanorfrajka@gmail.com>
Date: Sun, 16 Aug 2026 07:17:47 +0200
Subject: [PATCH 1/4] refactor: re-vendor report CSS/tokens, route figures
 through slots

---
 oceanarray/cli.py                             |  4 +-
 oceanarray/config/report_tokens.py            |  4 +-
 oceanarray/plotters/helpers.py                | 10 +--
 oceanarray/plotters/timeseries.py             |  2 +-
 oceanarray/reports/_css.py                    | 72 +++++++++++++--
 oceanarray/reports/_plots.py                  | 13 ++-
 oceanarray/reports/templates/array.html       | 11 +--
 oceanarray/reports/templates/base.html        |  6 +-
 oceanarray/reports/templates/grid.html        | 39 ++++----
 oceanarray/reports/templates/instrument.html  | 20 ++---
 oceanarray/reports/templates/mooring.html     | 30 +++----
 oceanarray/reports/templates/stack.html       | 41 ++++-----
 .../dune2/dune2_1_2026_grid_report.html       | 89 ++++++++++++-------
 .../golden/dune2/dune2_1_2026_report.html     | 74 +++++++++------
 .../dune2/dune2_1_2026_stack_report.html      | 85 ++++++++++++------
 .../instrument/dune2_1_2026_2941_report.html  | 64 ++++++++-----
 .../instrument/dune2_1_2026_9920_report.html  | 66 +++++++++-----
 tests/unit/test_report_golden.py              |  7 +-
 tests/unit/test_report_tokens.py              |  2 +
 19 files changed, 393 insertions(+), 246 deletions(-)

diff --git a/oceanarray/cli.py b/oceanarray/cli.py
index 832a956..caa1273 100644
--- a/oceanarray/cli.py
+++ b/oceanarray/cli.py
@@ -829,13 +829,11 @@ def _stage_token(value: str) -> "int | str":
         If *value* is not recognised by :func:`~oceanarray.processors.resolve_stage`.
 
     """
-    import argparse as _ap
-
     coerced: int | str = int(value) if value.isdigit() else value
     try:
         resolve_stage(coerced)
     except ValueError as exc:
-        raise _ap.ArgumentTypeError(str(exc)) from exc
+        raise argparse.ArgumentTypeError(str(exc)) from exc
     return coerced
 
 
diff --git a/oceanarray/config/report_tokens.py b/oceanarray/config/report_tokens.py
index 8750523..51c23e9 100644
--- a/oceanarray/config/report_tokens.py
+++ b/oceanarray/config/report_tokens.py
@@ -59,7 +59,7 @@
 # Invariant asserted by the slot-contract test: inches == W_FULL * fraction, so
 # display_px / fig_in is identical for every figure and one font size renders at
 # one on-screen size everywhere.  Test 2 asserts each saved PNG is exactly
-# round(inches * FIG_DPI) px wide (1350 / 900 / 810 / 675 / 540 / 450).
+# round(inches * FIG_DPI) px wide (1350 / 900 / 810 / 675 / 540 / 450 / 338).
 SLOTS: dict[str, tuple[float, float]] = {
     "full": (1.0, 9.0),
     "twothirds": (2 / 3, 6.0),
@@ -67,6 +67,7 @@
     "half": (0.5, 4.5),
     "two-fifths": (0.4, 3.6),
     "third": (1 / 3, 3.0),
+    "quarter": (0.25, 2.25),
 }
 
 # Ergonomic width aliases (inches) for plotter call sites; derived from SLOTS.
@@ -75,6 +76,7 @@
 W_HALF: float = SLOTS["half"][1]
 W_TWO_FIFTHS: float = SLOTS["two-fifths"][1]
 W_THIRD: float = SLOTS["third"][1]
+W_QUARTER: float = SLOTS["quarter"][1]
 
 # Aspect-locked figure constants (spec §14).
 SECTION_STRETCH: float = (
diff --git a/oceanarray/plotters/helpers.py b/oceanarray/plotters/helpers.py
index 1361e10..3629308 100644
--- a/oceanarray/plotters/helpers.py
+++ b/oceanarray/plotters/helpers.py
@@ -3,14 +3,8 @@
 Provides colormap helpers and rose-diagram rendering used across multiple
 Tier-2 plotter modules.
 
-Post-OdB: still to migrate from report/_plots.py:
-  _instrument_panels, _CANONICAL_PANELS, _COMPACT_PANEL_VARS,
-  _ts_heatmap_panel, _add_sigma0_contours, _xyz_to_enu_2d.
-
-Also migrate _instrument_label from plotter.py.
-
-Note: _fig_to_base64 stays in report/_html_helpers.py (called only by
-Tier-3 wrappers in report/_plots.py; plotters/ never serialises to base64).
+Note: _fig_to_base64 stays in reports/_html_helpers.py (called only by
+Tier-3 wrappers in reports/_plots.py; plotters/ never serialises to base64).
 """
 
 from __future__ import annotations
diff --git a/oceanarray/plotters/timeseries.py b/oceanarray/plotters/timeseries.py
index 2c4dc4b..313cc17 100644
--- a/oceanarray/plotters/timeseries.py
+++ b/oceanarray/plotters/timeseries.py
@@ -288,7 +288,7 @@ def draw_grid_velocity_stacked(
 
     """
     import matplotlib.pyplot as plt
-    from ..reports._plots import _velocity_panel_style
+    from .helpers import _velocity_panel_style
 
     vel_vars = [
         "east_velocity",
diff --git a/oceanarray/reports/_css.py b/oceanarray/reports/_css.py
index 504d428..236945b 100644
--- a/oceanarray/reports/_css.py
+++ b/oceanarray/reports/_css.py
@@ -76,7 +76,9 @@ def emit_css(package: str) -> str:
     are the current values, not a redesign).  The only additions over
     the previous hand-written stylesheet are the package accent's two homes — a
     masthead ``.wordmark`` and the footer's ``border-top`` — plus the ``78ch``
-    reading measure and the structural ``break-inside`` print rules.
+    reading measure and the ``@media print`` rules for browser printing.  (The
+    PDF renderer additionally injects :func:`print_css`, which layers ``@page``
+    geometry on top for the WeasyPrint path.)
 
     Parameters
     ----------
@@ -98,15 +100,15 @@ def emit_css(package: str) -> str:
 p, li {{ max-width: 78ch; }}
 .masthead {{
   background: var(--ocean); color: #fff; position: relative;
-  padding: 1.6rem 2rem; border-radius: 8px; margin-bottom: 2rem;
+  padding: 1.6rem 2rem; border-radius: var(--radius-card); margin-bottom: 2rem;
 }}
 .masthead h1 {{ margin: 0 0 0.3rem; font-size: var(--fs-h1); font-weight: 700; }}
-.masthead .sub {{ font-size: var(--fs-meta); opacity: 0.85; margin: 0 0 0.15rem; }}
+.masthead .sub {{ font-size: var(--fs-meta); opacity: 0.85; margin: 0 0 0.15rem; max-width: none; }}
 .wordmark {{
   position: absolute; right: 2rem; bottom: 1.2rem;
   font-size: var(--fs-dt); font-weight: 700; letter-spacing: 0.04em;
   color: var(--package-accent); background: #fff; opacity: 0.85;
-  padding: 0.1rem 0.5rem; border-radius: 999px; text-decoration: none;
+  padding: 0.1rem 0.5rem; border-radius: var(--radius-pill); text-decoration: none;
 }}
 .wordmark:hover {{ opacity: 1; }}
 .meta-grid {{
@@ -130,10 +132,23 @@ def emit_css(package: str) -> str:
   text-decoration: none; margin-left: auto;
 }}
 .top-link:hover {{ color: var(--ocean); text-decoration: underline; }}
-.note {{
+.caption {{
   color: var(--gray-5); font-size: var(--fs-note);
-  margin-top: -0.5rem; margin-bottom: 0.75rem;
+  margin-top: 0.75rem; margin-bottom: 0.75rem;
 }}
+h2 + .caption {{ margin-top: -0.5rem; }}
+.explainer {{
+  font-size: var(--fs-note); color: var(--text);
+  background: var(--bg-sunken); border-left: 3px solid var(--muted);
+  padding: var(--sp-3); margin: -0.25rem 0 0.75rem; border-radius: var(--radius-btn);
+}}
+.warn {{
+  font-size: var(--fs-note); color: var(--text);
+  background: var(--warn-bg); border-left: 3px solid var(--warn);
+  padding: var(--sp-3); margin-bottom: 0.5rem; border-radius: var(--radius-btn);
+}}
+.warn::before {{ content: "⚠ "; }}
+.warn.error {{ border-left-color: var(--error); }}
 .jump-nav {{
   background: var(--seafoam); padding: 0.55rem 1rem;
   border-radius: 6px; margin-bottom: 1.5rem;
@@ -152,10 +167,26 @@ def emit_css(package: str) -> str:
 .fig-col {{ display: flex; flex-direction: column; gap: 0.75rem; }}
 figure {{ margin: 0; }}
 figure img {{
-  border: 1px solid var(--rule); border-radius: 4px;
+  border: 1px solid var(--rule); border-radius: var(--radius-btn);
   display: block; width: 100%; height: auto;
 }}
 figcaption {{ font-size: var(--fs-cap); color: var(--gray-5); margin-top: 0.25rem; }}
+table {{
+  width: 100%; border-collapse: collapse;
+  font-size: var(--fs-note); margin: 0.6rem 0 1.2rem;
+}}
+th {{
+  background: var(--package-accent); color: #fff; text-align: left;
+  font-weight: 600; padding: 0.4rem 0.65rem;
+}}
+th.num {{ text-align: right; }}
+td {{
+  padding: 0.35rem 0.65rem; border-bottom: 1px solid var(--rule);
+  vertical-align: top;
+}}
+tr:nth-child(even) td {{ background: var(--bg-sunken); }}
+td.num, .num {{ text-align: right; font-variant-numeric: tabular-nums; }}
+td.mono {{ font-family: var(--font-mono); font-size: var(--fs-xs); }}
 {slots}
 .masthead-header {{
   display: flex; justify-content: space-between; align-items: flex-start;
@@ -169,7 +200,7 @@ def emit_css(package: str) -> str:
 .nav-btns {{ display: flex; gap: 0.5rem; }}
 .btn-nav {{
   background: var(--ocean); color: #fff; padding: 0.25rem 0.75rem;
-  border-radius: 999px; text-decoration: none; font-size: var(--fs-nav);
+  border-radius: var(--radius-pill); text-decoration: none; font-size: var(--fs-nav);
 }}
 .btn-nav:hover {{ opacity: 0.85; }}
 footer {{
@@ -190,6 +221,31 @@ def emit_css(package: str) -> str:
 """
 
 
+def print_css(*, terse: bool = False) -> str:
+    """Return the print stylesheet, injected at PDF render time (spec §8.1).
+
+    These WeasyPrint-specific rules are kept out of the screen stylesheet so
+    screen output is byte-identical; a PDF renderer appends them at render time.
+    The shared stylesheet keeps only the structural ``@media print`` rules (page
+    breaks).  With *terse* ``True`` the ``.explainer`` prose is hidden (the
+    ``--pdf-terse`` variant); by default nothing is hidden — captions, explainers
+    and warnings all print.
+    """
+    css = """\
+@page { size: A4; margin: 18mm 16mm 20mm 16mm; }
+body { max-width: 100%; padding: 0; }
+p, li, .explainer { max-width: 78ch; }
+img { max-width: 100%; height: auto; }
+.masthead { -webkit-print-color-adjust: exact; print-color-adjust: exact; padding: 0.9rem 1.25rem; }
+.masthead-header h1, .masthead h1 { font-size: var(--fs-h1); }
+.meta-grid { grid-template-columns: repeat(4, 1fr); gap: 0.3rem 1rem; font-size: var(--fs-xs); }
+.jump-nav, .nav-btns, .btn-nav, .top-link { display: none; }
+"""
+    if terse:
+        css += ".explainer { display: none; }\n"
+    return css
+
+
 _JS_TOP_LINKS: str = """\
 <script>
 document.querySelectorAll('h2').forEach(h => {
diff --git a/oceanarray/reports/_plots.py b/oceanarray/reports/_plots.py
index c6087fd..0f7813a 100644
--- a/oceanarray/reports/_plots.py
+++ b/oceanarray/reports/_plots.py
@@ -23,7 +23,6 @@
 )
 from ..plotters.helpers import (  # noqa: F401
     _rose_ax,
-    _velocity_panel_style,
     grid_despine,
 )
 from ..plotters.timeseries import (
@@ -659,11 +658,11 @@ def _make_speed_boxplot(nc_path: str) -> Optional[str]:
     import xarray as xr
     from oceanarray.plotters.current import plot_speed_boxplot
 
-    def _draw() -> "plt.Figure":
+    def _draw(*, width_in: float = report_tokens.W_QUARTER) -> "plt.Figure":
         with xr.open_dataset(nc_path) as ds:
-            return plot_speed_boxplot(ds)
+            return plot_speed_boxplot(ds, width_in=width_in)
 
-    return render_b64(_draw, optional=True)
+    return render_slot(_draw, slot="quarter", optional=True)
 
 
 def _make_hodograph_b64(nc_path: str) -> Optional[str]:
@@ -866,7 +865,7 @@ def _make_knockdown_hab_b64(ds: "xr.Dataset") -> Optional[str]:
     """
     from oceanarray.plotters.diagnostic import plot_knockdown_hab
 
-    return render_b64(plot_knockdown_hab, ds, optional=True)
+    return render_slot(plot_knockdown_hab, ds, slot="half", optional=True)
 
 
 def _make_knockdown_displacement_b64(ds: "xr.Dataset") -> Optional[str]:
@@ -879,7 +878,7 @@ def _make_knockdown_displacement_b64(ds: "xr.Dataset") -> Optional[str]:
     """
     from oceanarray.plotters.diagnostic import plot_knockdown_displacement
 
-    return render_b64(plot_knockdown_displacement, ds, optional=True)
+    return render_slot(plot_knockdown_displacement, ds, slot="full", optional=True)
 
 
 def _make_knockdown_anomaly_b64(ds: "xr.Dataset") -> Optional[str]:
@@ -893,7 +892,7 @@ def _make_knockdown_anomaly_b64(ds: "xr.Dataset") -> Optional[str]:
     """
     from oceanarray.plotters.diagnostic import plot_knockdown_anomaly
 
-    return render_b64(plot_knockdown_anomaly, ds, optional=True)
+    return render_slot(plot_knockdown_anomaly, ds, slot="half", optional=True)
 
 
 def _make_clock_check_b64(
diff --git a/oceanarray/reports/templates/array.html b/oceanarray/reports/templates/array.html
index a8ed13f..491e955 100644
--- a/oceanarray/reports/templates/array.html
+++ b/oceanarray/reports/templates/array.html
@@ -2,20 +2,15 @@
 {% import "_macros.html" as m %}
 {% block title %}{{ array_name }} &ndash; array summary{% endblock %}
 {% block page_styles %}
+  /* Table + caption styles are canonical in emit_css now. */
   .meta-grid div { font-size:0.82rem; }
-  table { border-collapse:collapse; width:100%; margin:0.6rem 0 1.2rem; font-size:0.84rem; }
-  th { background:var(--ocean); color:#fff; padding:0.4rem 0.6rem; text-align:left; }
-  td { padding:0.35rem 0.6rem; border-bottom:1px solid #e8ecef; }
-  tr:nth-child(even) td { background:#f7f9fb; }
-  .num { text-align:right; }
   .btn { display:inline-block; padding:0.15em 0.55em; border-radius:4px; font-size:0.75rem;
          font-weight:700; text-decoration:none; color:#fff; margin:0 0.15rem 0.2rem 0; }
   .btn-sum { background:#2c3e50; }
   .btn-stk { background:#2980b9; }
   .btn-grd { background:#8e44ad; }
   .btn-miss { background:#bbb; cursor:default; pointer-events:none; }
-  .note { font-size:0.78rem; color:#555; margin:0.2rem 0 0.6rem; }
-  .fig { max-width:60%; display:block; margin:0.5rem auto 1rem; border:1px solid #e0e4e8; border-radius:4px; }
+  .fig { max-width:60%; display:block; margin:0.5rem auto 1rem; border:1px solid var(--rule); border-radius:4px; }
 {% endblock %}
 {% block masthead_title %}{{ array_name }}{% endblock %}
 {% block masthead_type %}Array{% endblock %}
@@ -31,7 +26,7 @@
   {% endblock %}
 {% block content %}
 
-<p class="note" style="margin:0 0 0.8rem">
+<p class="caption" style="margin:0 0 0.8rem">
   Jump to:
   <a href="#moorings">Moorings</a> &bull;
   <a href="#type-summary">Instrument summary</a> &bull;
diff --git a/oceanarray/reports/templates/base.html b/oceanarray/reports/templates/base.html
index 288610f..9e52b67 100644
--- a/oceanarray/reports/templates/base.html
+++ b/oceanarray/reports/templates/base.html
@@ -54,8 +54,10 @@
 /* Figures never exceed the content column; the oversampled PNG downscales
    crisply (spec §11 OVERSAMPLE). Pages may override (e.g. array uses 60%). */
 .fig { max-width:100%; height:auto; display:block; }
-td.num { text-align:right; font-variant-numeric:tabular-nums; }
-td.mono { font-family:var(--font-mono); font-size:var(--fs-xs); }
+/* A bare .fig (no slot class) is a full-width figure: fill the column. A
+   slot-* figure gets its width from the .slot-* rule instead — so this must NOT
+   apply to slotted figures (that was the width:100%-overrides-slot bug). */
+.fig:not([class*="slot-"]) { width:100%; }
 .none-note { color:var(--muted); font-style:italic; }
 .var-qc { color:var(--good); font-size:var(--fs-xs); }
 /* Figure-debug line under a plot (OCEANARRAY_REPORT_DEBUG=1): slot the
diff --git a/oceanarray/reports/templates/grid.html b/oceanarray/reports/templates/grid.html
index f93f473..e7d5d6a 100644
--- a/oceanarray/reports/templates/grid.html
+++ b/oceanarray/reports/templates/grid.html
@@ -7,13 +7,8 @@
      .fig fills via base.html's max-width:100%.  Setting width:100% here would
      override the slot and force every figure full-width (U0.2). */
   .fig { border:1px solid var(--rule); border-radius:var(--radius-btn); margin-bottom:0.5rem; }
-  .note { color:var(--muted); font-size:0.82rem; margin-top:-0.5rem; }
+  /* Table + caption styles are canonical in emit_css now (.var-table drops to the shared table style). */
   .style-label { font-size:0.8rem; font-weight:600; color:var(--muted); margin:0.4rem 0 0.2rem; text-transform:uppercase; letter-spacing:0.05em; }
-  .var-table { width:100%; border-collapse:collapse; font-size:0.82rem; margin-bottom:1.5rem; }
-  .var-table th { background:var(--seafoam); text-align:left; padding:0.4rem 0.6rem; border-bottom:2px solid #cde; }
-  .var-table td { padding:0.3rem 0.6rem; border-bottom:1px solid #eef; vertical-align:top; }
-  .var-table tr:nth-child(even) td { background:#f4f9fc; }
-  .var-table tr:hover td { background:#e8f4f8; }
   details summary.collapse-toggle { color:var(--muted); font-size:0.76rem; cursor:pointer;
     list-style:none; padding:0.15rem 0 0.4rem; user-select:none; }
   details summary.collapse-toggle::before { content:"▾ "; }
@@ -73,7 +68,7 @@ <h2 id="history">Processing history</h2>
 <!-- ══ Hydrography: T and S ══ -->
 {% if fig_hydro_b64 %}
 <h2 id="hydro">Hydrography</h2>
-<p class="note">Temperature, salinity, dissolved oxygen, and O₂ saturation (when present). Vertically interpolated to regular pressure grid &bull; 20 discrete colour levels.</p>
+<p class="caption">Temperature, salinity, dissolved oxygen, and O₂ saturation (when present). Vertically interpolated to regular pressure grid &bull; 20 discrete colour levels.</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,{{ fig_hydro_b64 }}" alt="Temperature and salinity">
 {{- m.dbg(fig_hydro_b64, "full (100%)") }}
@@ -83,7 +78,7 @@ <h2 id="hydro">Hydrography</h2>
 <!-- ══ Velocity: E / N / Up ══ -->
 {% if fig_vel_stacked_b64 %}
 <h2 id="vel">Velocity</h2>
-<p class="note">East, north, and up velocity. QC-flagged samples excluded before interpolation. Shared symmetric Spectral_r colormap for east/north; separate bounds for up. No temporal gap fill — NaN where no data.</p>
+<p class="caption">East, north, and up velocity. QC-flagged samples excluded before interpolation. Shared symmetric Spectral_r colormap for east/north; separate bounds for up. No temporal gap fill — NaN where no data.</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,{{ fig_vel_stacked_b64 }}" alt="Velocity pcolormesh">
 {{- m.dbg(fig_vel_stacked_b64, "full (100%)") }}
@@ -93,7 +88,7 @@ <h2 id="vel">Velocity</h2>
 <!-- ══ T-S diagram (before derived quantities) ══ -->
 {% if fig_ts_grid_b64 %}
 <h2 id="ts">T-S diagram</h2>
-<p class="note">Left: log₁₀(count+1) per T-S bin. Right (when O₂ present): median O₂ saturation per T-S bin — bins with &lt;5 samples masked. Colour scale: BrBG (brown=low, teal=high).</p>
+<p class="caption">Left: log₁₀(count+1) per T-S bin. Right (when O₂ present): median O₂ saturation per T-S bin — bins with &lt;5 samples masked. Colour scale: BrBG (brown=low, teal=high).</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig slot-{{ slot_for(fig_ts_grid_b64) }}" src="data:image/png;base64,{{ fig_ts_grid_b64 }}" alt="T-S diagram">
 {{- m.dbg(fig_ts_grid_b64, "slot-" ~ slot_for(fig_ts_grid_b64)) }}
@@ -103,7 +98,7 @@ <h2 id="ts">T-S diagram</h2>
 <!-- ══ Velocity IQR profiles ══ -->
 {% if fig_vel_iqr_b64 %}
 <h2 id="vel-iqr">Velocity IQR profiles</h2>
-<p class="note">Median (solid line) and interquartile range (shaded, 25–75 %) across the full deployment at each pressure level. 2.5–97.5 % outer envelope for speed. Right panel: count of non-NaN values per depth.</p>
+<p class="caption">Median (solid line) and interquartile range (shaded, 25–75 %) across the full deployment at each pressure level. 2.5–97.5 % outer envelope for speed. Right panel: count of non-NaN values per depth.</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,{{ fig_vel_iqr_b64 }}" alt="Velocity IQR profiles">
 {{- m.dbg(fig_vel_iqr_b64, "full (100%)") }}
@@ -113,7 +108,7 @@ <h2 id="vel-iqr">Velocity IQR profiles</h2>
 <!-- ══ Current roses per pressure level ══ -->
 {% if fig_grid_rose_b64 %}
 <h2 id="grid-rose">Current roses</h2>
-<p class="note">One rose per pressure level (up to 12, evenly subsampled). Suspect/bad QC excluded. Each petal shows the fraction of time current flowed in that direction; petal length encodes speed (m s⁻¹).</p>
+<p class="caption">One rose per pressure level (up to 12, evenly subsampled). Suspect/bad QC excluded. Each petal shows the fraction of time current flowed in that direction; petal length encodes speed (m s⁻¹).</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,{{ fig_grid_rose_b64 }}" alt="Current roses by pressure level">
 {{- m.dbg(fig_grid_rose_b64, "full (100%)") }}
@@ -123,7 +118,7 @@ <h2 id="grid-rose">Current roses</h2>
 <!-- ══ Hodograph ══ -->
 {% if fig_grid_hodograph_b64 %}
 <h2 id="grid-hodograph">Hodograph</h2>
-<p class="note">Current hodographs at two pressure levels (25th and 75th percentile of the valid range). Top row = shallower level; bottom row = deeper level. Left = Tukey-smoothed raw; right = eddy component (LP mean removed). Colour indicates fractional time through the deployment (lime circle = start, red square = end). QC-bad data excluded.</p>
+<p class="caption">Current hodographs at two pressure levels (25th and 75th percentile of the valid range). Top row = shallower level; bottom row = deeper level. Left = Tukey-smoothed raw; right = eddy component (LP mean removed). Colour indicates fractional time through the deployment (lime circle = start, red square = end). QC-bad data excluded.</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,{{ fig_grid_hodograph_b64 }}" alt="Hodograph at two pressure levels">
 {{- m.dbg(fig_grid_hodograph_b64, "full (100%)") }}
@@ -133,7 +128,7 @@ <h2 id="grid-hodograph">Hodograph</h2>
 <!-- ══ Particle trajectory ══ -->
 {% if fig_grid_traj_b64 %}
 <h2 id="grid-traj">Particle trajectory</h2>
-<p class="note">Pseudo-Lagrangian trajectories at each gridded pressure level, integrated from east and north velocity (Euler forward). All start at the origin. Coloured by pressure (dbar).</p>
+<p class="caption">Pseudo-Lagrangian trajectories at each gridded pressure level, integrated from east and north velocity (Euler forward). All start at the origin. Coloured by pressure (dbar).</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig slot-{{ slot_for(fig_grid_traj_b64) }}" src="data:image/png;base64,{{ fig_grid_traj_b64 }}" alt="Grid particle trajectory">
 {{- m.dbg(fig_grid_traj_b64, "slot-" ~ slot_for(fig_grid_traj_b64)) }}
@@ -143,7 +138,7 @@ <h2 id="grid-traj">Particle trajectory</h2>
 <!-- ══ Velocity time series at depth of max speed ══ -->
 {% if fig_grid_ts_b64 %}
 <h2 id="grid-ts">Velocity time series at depth of maximum mean speed</h2>
-<p class="note">Depth chosen as the pressure level with the highest time-mean current speed. Speed, east, and north velocity at that level.</p>
+<p class="caption">Depth chosen as the pressure level with the highest time-mean current speed. Speed, east, and north velocity at that level.</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,{{ fig_grid_ts_b64 }}" alt="Velocity time series at max-speed depth">
 {{- m.dbg(fig_grid_ts_b64, "full (100%)") }}
@@ -156,7 +151,7 @@ <h2 id="strat">Stratification</h2>
 {% endif %}
 
 {% if fig_sigma_b64 %}
-<p class="note">Potential density. 20 discrete colour levels.</p>
+<p class="caption">Potential density. 20 discrete colour levels.</p>
 <details open><summary class="collapse-toggle">show / hide sigma0</summary>
 <img class="fig" src="data:image/png;base64,{{ fig_sigma_b64 }}" alt="Potential density pcolormesh">
 {{- m.dbg(fig_sigma_b64, "full (100%)") }}
@@ -165,7 +160,7 @@ <h2 id="strat">Stratification</h2>
 
 {% if fig_n2_b64 %}
 <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;">Buoyancy frequency squared (N²)</h3>
-<p class="note">log₁₀(N²) in s⁻². Purple = strongly stratified; yellow = weakly stratified. Computed from T and S via GSW.</p>
+<p class="caption">log₁₀(N²) in s⁻². Purple = strongly stratified; yellow = weakly stratified. Computed from T and S via GSW.</p>
 <details open><summary class="collapse-toggle">show / hide N²</summary>
 <img class="fig" src="data:image/png;base64,{{ fig_n2_b64 }}" alt="N² pcolormesh">
 {{- m.dbg(fig_n2_b64, "full (100%)") }}
@@ -178,7 +173,7 @@ <h2 id="overflow">Overflow</h2>
 
 {% if fig_isopycnal_coverage_b64 %}
 <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;">Isopycnal coverage diagnostic</h3>
-<p class="note">Percentage of time steps during which each σ₀ surface (0.1&nbsp;kg&nbsp;m⁻³ spacing) lies within the measured column range. Green&nbsp;≥&nbsp;80&nbsp;%; amber&nbsp;50–80&nbsp;%; red&nbsp;&lt;&nbsp;50&nbsp;%. Orange diamond&nbsp;= current <code>--sig-level</code> target. Dashed line&nbsp;=&nbsp;80&nbsp;% threshold. NaN gaps in the tracking figure above correspond to times when the isopycnal is outside the measured range (pycnocline above the shallowest grid level, or below the deepest).</p>
+<p class="caption">Percentage of time steps during which each σ₀ surface (0.1&nbsp;kg&nbsp;m⁻³ spacing) lies within the measured column range. Green&nbsp;≥&nbsp;80&nbsp;%; amber&nbsp;50–80&nbsp;%; red&nbsp;&lt;&nbsp;50&nbsp;%. Orange diamond&nbsp;= current <code>--sig-level</code> target. Dashed line&nbsp;=&nbsp;80&nbsp;% threshold. NaN gaps in the tracking figure above correspond to times when the isopycnal is outside the measured range (pycnocline above the shallowest grid level, or below the deepest).</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,{{ fig_isopycnal_coverage_b64 }}" alt="Isopycnal coverage diagnostic">
 {{- m.dbg(fig_isopycnal_coverage_b64, "full (100%)") }}
@@ -188,7 +183,7 @@ <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;">Isopycna
 {% for sec in sigma_sections %}
 {% if sec.isopycnal_b64 %}
 <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;">Isopycnal height above seabed &mdash; {{ sec.name }}</h3>
-<p class="note">Height above seabed (m) of each target σ₀ surface through time. Tracked by linear interpolation in density space from the gridded {{ sec.name }} field; 1-hour running median applied. NaN where the surface outcrops or is outside the observed range. Light blue = lighter water (shallower); dark blue = denser water (deeper). Targets set by <code>--sig-level</code> (default σ₀&nbsp;=&nbsp;27.70).</p>
+<p class="caption">Height above seabed (m) of each target σ₀ surface through time. Tracked by linear interpolation in density space from the gridded {{ sec.name }} field; 1-hour running median applied. NaN where the surface outcrops or is outside the observed range. Light blue = lighter water (shallower); dark blue = denser water (deeper). Targets set by <code>--sig-level</code> (default σ₀&nbsp;=&nbsp;27.70).</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,{{ sec.isopycnal_b64 }}" alt="Isopycnal height above seabed">
 </details>
@@ -197,7 +192,7 @@ <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;">Isopycna
 
 {% if fig_overflow_temp_b64 %}
 <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;">Temperature ~100 m above seabed</h3>
-<p class="note">1-hour running median temperature at the grid pressure level nearest to 100&nbsp;m above the seabed. Level and height-above-seabed shown in figure title.</p>
+<p class="caption">1-hour running median temperature at the grid pressure level nearest to 100&nbsp;m above the seabed. Level and height-above-seabed shown in figure title.</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,{{ fig_overflow_temp_b64 }}" alt="Temperature near seabed">
 {{- m.dbg(fig_overflow_temp_b64, "full (100%)") }}
@@ -206,7 +201,7 @@ <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;">Temperat
 
 {% if fig_spectrum_b64 %}
 <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;" id="spectrum">Temperature power spectrum</h3>
-<p class="note"><strong>Left:</strong> low-frequency overview — 14-day Hann windows, 50&nbsp;% overlap. <strong>Right:</strong> high-frequency zoom — 1-day windows (~14&times; more windows, smoother tidal/inertial estimate); x-axis in hours. LF markers: M2, 1.8&nbsp;d, 4&nbsp;d, f. HF markers: M2 (12.4&nbsp;h), f (inertial). Dashed black line: &minus;2 spectral slope. Colour encodes pressure (light blue = shallow, dark blue = deep). Window length controllable via <code>hf_segment_days</code> in <code>_make_spectrum_fig_b64</code>.</p>
+<p class="caption"><strong>Left:</strong> low-frequency overview — 14-day Hann windows, 50&nbsp;% overlap. <strong>Right:</strong> high-frequency zoom — 1-day windows (~14&times; more windows, smoother tidal/inertial estimate); x-axis in hours. LF markers: M2, 1.8&nbsp;d, 4&nbsp;d, f. HF markers: M2 (12.4&nbsp;h), f (inertial). Dashed black line: &minus;2 spectral slope. Colour encodes pressure (light blue = shallow, dark blue = deep). Window length controllable via <code>hf_segment_days</code> in <code>_make_spectrum_fig_b64</code>.</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,{{ fig_spectrum_b64 }}" alt="Temperature power spectrum">
 {{- m.dbg(fig_spectrum_b64, "full (100%)") }}
@@ -215,7 +210,7 @@ <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;" id="spec
 
 {% if fig_wavelet_b64 %}
 <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;" id="wavelet">Temperature wavelet scalogram</h3>
-<p class="note">Continuous wavelet transform (Morlet, &omega;<sub>0</sub>&nbsp;=&nbsp;6; Torrence &amp; Compo 1998).  Three depth levels: 2nd from top, middle, 2nd from bottom of the 100-dbar-multiple valid levels.  Colour shows log<sub>10</sub>(power) (°C²&nbsp;d); hatched grey region = cone of influence (edge-affected); hatched cross region = gap-filled data; black contour = 95&nbsp;% significance against red noise.</p>
+<p class="caption">Continuous wavelet transform (Morlet, &omega;<sub>0</sub>&nbsp;=&nbsp;6; Torrence &amp; Compo 1998).  Three depth levels: 2nd from top, middle, 2nd from bottom of the 100-dbar-multiple valid levels.  Colour shows log<sub>10</sub>(power) (°C²&nbsp;d); hatched grey region = cone of influence (edge-affected); hatched cross region = gap-filled data; black contour = 95&nbsp;% significance against red noise.</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,{{ fig_wavelet_b64 }}" alt="Temperature wavelet scalogram">
 {{- m.dbg(fig_wavelet_b64, "full (100%)") }}
@@ -224,7 +219,7 @@ <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;" id="wave
 
 {% if fig_rotary_b64 %}
 <h2 id="rotary">Rotary velocity spectrum</h2>
-<p class="note">CW (clockwise, anticyclonic, solid red lines) and CCW (counter-clockwise, cyclonic, dashed blue lines) power spectra and rotary coefficient r&nbsp;=&nbsp;(CCW&minus;CW)/(CCW+CW). Welch PSD, Hann window, 14-day segments, 50&nbsp;% overlap. Up to 4 pressure levels (at most 1/5th of valid levels); colour encodes pressure depth. Vertical lines: M2, K1, 1.8&nbsp;d, 4&nbsp;d, and inertial period (f). r&nbsp;&gt;&nbsp;0&nbsp;=&nbsp;CCW dominant; r&nbsp;&lt;&nbsp;0&nbsp;=&nbsp;CW dominant. Physical interpretation (NH): inertial oscillations are inherently CW; for internal waves (f&nbsp;&lt;&nbsp;&omega;), CW dominance indicates upward energy propagation / downward phase propagation (Leaman &amp; Sanford 1975).</p>
+<p class="caption">CW (clockwise, anticyclonic, solid red lines) and CCW (counter-clockwise, cyclonic, dashed blue lines) power spectra and rotary coefficient r&nbsp;=&nbsp;(CCW&minus;CW)/(CCW+CW). Welch PSD, Hann window, 14-day segments, 50&nbsp;% overlap. Up to 4 pressure levels (at most 1/5th of valid levels); colour encodes pressure depth. Vertical lines: M2, K1, 1.8&nbsp;d, 4&nbsp;d, and inertial period (f). r&nbsp;&gt;&nbsp;0&nbsp;=&nbsp;CCW dominant; r&nbsp;&lt;&nbsp;0&nbsp;=&nbsp;CW dominant. Physical interpretation (NH): inertial oscillations are inherently CW; for internal waves (f&nbsp;&lt;&nbsp;&omega;), CW dominance indicates upward energy propagation / downward phase propagation (Leaman &amp; Sanford 1975).</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,{{ fig_rotary_b64 }}" alt="Rotary velocity spectrum">
 {{- m.dbg(fig_rotary_b64, "full (100%)") }}
diff --git a/oceanarray/reports/templates/instrument.html b/oceanarray/reports/templates/instrument.html
index 63f9de0..f3b8776 100644
--- a/oceanarray/reports/templates/instrument.html
+++ b/oceanarray/reports/templates/instrument.html
@@ -3,18 +3,10 @@
 {% block title %}{{ instr_type | title }} &ndash; s/n {{ serial }}{% endblock %}
 {% block page_styles %}
   :root { --accent:#1e8449; --accent-link:#d5f5e3; }
-  .file-table { width:100%; border-collapse:collapse; font-size:0.81rem; margin-bottom:1.2rem; }
-  .file-table th { background:var(--seafoam); color:var(--text); text-align:left;
-                   padding:0.35rem 0.65rem; border-bottom:2px solid #cde; font-weight:700; }
-  .file-table td { padding:0.3rem 0.65rem; border-bottom:1px solid #eef; vertical-align:middle; }
-  .file-table tr:nth-child(even) td { background:#f4f9fc; }
+  /* Table style is canonical in emit_css now; only the file-table's cell
+     colour classes remain page-specific. */
   .file-table .ok { color:var(--good); font-weight:700; }
-  .file-table .miss { color:#bbb; }
-  table { width:100%; border-collapse:collapse; font-size:0.82rem; }
-  th { background:var(--ocean); color:#fff; padding:0.4rem 0.65rem;
-       text-align:left; font-weight:600; white-space:nowrap; }
-  td { padding:0.35rem 0.65rem; border-bottom:1px solid #ecf0f1; vertical-align:middle; }
-  tr:nth-child(even) td { background:var(--seafoam); }
+  .file-table .miss { color:var(--gray-3); }
   .badge { display:inline-block; padding:0.12em 0.45em; border-radius:3px;
            font-size:0.7rem; font-weight:700; white-space:nowrap; }
   .b-ok   { background:var(--good);   color:#fff; }
@@ -254,14 +246,14 @@ <h2 id="hodograph">Hodograph</h2>
 <!-- ══ Speed distribution ══ -->
 {% if fig_speed_boxplot_b64 %}
 <h2 id="speed">Current speed distribution</h2>
-<img class="fig" src="data:image/png;base64,{{ fig_speed_boxplot_b64 }}" style="max-width:300px;">
-{{- m.dbg(fig_speed_boxplot_b64, "max-width 300px") }}
+<img class="fig slot-{{ slot_for(fig_speed_boxplot_b64) }}" src="data:image/png;base64,{{ fig_speed_boxplot_b64 }}">
+{{- m.dbg(fig_speed_boxplot_b64, "slot-" ~ slot_for(fig_speed_boxplot_b64)) }}
 {% endif %}
 
 <!-- ══ Analog channels ══ -->
 {% if fig_analog_b64 %}
 <h2 id="analog">Analog channels</h2>
-<p class="note">
+<p class="caption">
   Full-record time series of analog channel variables containing non-zero, non-NaN data.
   One panel per channel.
   Labels and units are read from the mooring YAML — update them there to change what appears here.
diff --git a/oceanarray/reports/templates/mooring.html b/oceanarray/reports/templates/mooring.html
index 081fa3a..f3c6922 100644
--- a/oceanarray/reports/templates/mooring.html
+++ b/oceanarray/reports/templates/mooring.html
@@ -2,18 +2,8 @@
 {% import "_macros.html" as m %}
 {% block title %}{{ mooring_name }} &ndash; recovery report{% endblock %}
 {% block page_styles %}
-  table { width: 100%; border-collapse: collapse; font-size: 0.83rem; }
-  th {
-    background: var(--ocean);
-    color: #fff;
-    padding: 0.45rem 0.7rem;
-    text-align: left;
-    font-weight: 600;
-    white-space: nowrap;
-  }
-  td { padding: 0.38rem 0.7rem; border-bottom: 1px solid #ecf0f1; vertical-align: middle; }
-  tr:nth-child(even) td { background: var(--seafoam); }
-  tr:hover td { background: #d6eaf8; }
+  /* Table style is now canonical in emit_css (shared).  Only page-specific
+     content styles remain here. */
   .pipeline { white-space: nowrap; display: flex; flex-wrap: wrap; gap: 0.2rem; align-items: center; }
   .badge {
     display: inline-block;
@@ -492,7 +482,7 @@ <h2 id="clock">4 &mdash; Clock corrections</h2>
 
 {% if fig_clock_check_b64 %}
 <h3 style="font-size:0.9rem;margin-top:1.2rem;">Clock alignment check</h3>
-<p class="note">
+<p class="caption">
   Overlaid temperature records zoomed to the first and last 30 minutes of the deployment.
   If instrument clocks are misaligned the temperature curves will appear shifted in time.
   Data are from stage&#8209;3 (or stage&#8209;2 if stage&#8209;3 is not yet available).
@@ -669,33 +659,33 @@ <h2 id="knockdown">Mooring knockdown</h2>
 <div style="display:flex;gap:1rem;flex-wrap:wrap;align-items:flex-start">
 {% if fig_knockdown_hab_b64 %}
 <div style="flex:1;min-width:260px">
-<p class="note">Nominal HAB (x) vs. measured pressure (y). The dashed line shows expected pressure
+<p class="caption">Nominal HAB (x) vs. measured pressure (y). The dashed line shows expected pressure
   (water&nbsp;depth&nbsp;&minus;&nbsp;HAB). Instruments below the line were knocked down.
   Interpolated pressure (QC&nbsp;flag&nbsp;8) excluded.</p>
 <img style="width:100%;border:1px solid var(--rule);border-radius:4px" src="data:image/png;base64,{{ fig_knockdown_hab_b64 }}" alt="Knockdown HAB vs pressure">
-{{- m.dbg(fig_knockdown_hab_b64, "flex ~half column") }}
+{{- m.dbg(fig_knockdown_hab_b64, "slot-" ~ slot_for(fig_knockdown_hab_b64) ~ " (flex 2-up)") }}
 </div>
 {% endif %}
 {% if fig_knockdown_anomaly_b64 %}
 <div style="flex:1;min-width:260px">
-<p class="note">IQR of pressure anomaly (measured &minus; nominal) per instrument.
+<p class="caption">IQR of pressure anomaly (measured &minus; nominal) per instrument.
   Positive = deeper than design depth.
   <span style="color:mediumseagreen">Green</span> &lt;&nbsp;100&nbsp;dbar,
   <span style="color:goldenrod">yellow</span> 100–200,
   <span style="color:darkorange">amber</span> 200–300,
   <span style="color:firebrick">red</span> &gt;&nbsp;300&nbsp;dbar.</p>
 <img style="width:100%;border:1px solid var(--rule);border-radius:4px" src="data:image/png;base64,{{ fig_knockdown_anomaly_b64 }}" alt="Knockdown pressure anomaly">
-{{- m.dbg(fig_knockdown_anomaly_b64, "flex ~half column") }}
+{{- m.dbg(fig_knockdown_anomaly_b64, "slot-" ~ slot_for(fig_knockdown_anomaly_b64) ~ " (flex 2-up)") }}
 </div>
 {% endif %}
 </div>
 {% if fig_knockdown_displacement_b64 %}
-<p class="note">Estimated horizontal displacement (m) vs. measured pressure.
+<p class="caption">Estimated horizontal displacement (m) vs. measured pressure.
   Left: scatter per instrument; right: normalised 2-D density across all instruments.
   Displacement derived from the rigid-pendulum approximation:
   <em>x</em>&nbsp;=&nbsp;&radic;(hab<sub>nom</sub>&sup2;&nbsp;&minus;&nbsp;hab<sub>meas</sub>&sup2;).</p>
-<img style="width:100%;border:1px solid var(--rule);border-radius:4px" src="data:image/png;base64,{{ fig_knockdown_displacement_b64 }}" alt="Knockdown horizontal displacement">
-{{- m.dbg(fig_knockdown_displacement_b64, "width 100%") }}
+<img class="fig slot-{{ slot_for(fig_knockdown_displacement_b64) }}" style="border:1px solid var(--rule);border-radius:4px" src="data:image/png;base64,{{ fig_knockdown_displacement_b64 }}" alt="Knockdown horizontal displacement">
+{{- m.dbg(fig_knockdown_displacement_b64, "slot-" ~ slot_for(fig_knockdown_displacement_b64)) }}
 {% endif %}
 {% endif %}
 
diff --git a/oceanarray/reports/templates/stack.html b/oceanarray/reports/templates/stack.html
index 443665a..5b9bd77 100644
--- a/oceanarray/reports/templates/stack.html
+++ b/oceanarray/reports/templates/stack.html
@@ -5,12 +5,7 @@
   /* No width here: the slot class sets each figure's width (U0.2); width:100%
      would override the slot and force full-width. */
   .fig { border:1px solid var(--rule); border-radius:var(--radius-btn); margin-bottom:1.5rem; }
-  .var-table, .instr-table { width:100%; border-collapse:collapse; font-size:0.82rem; margin-bottom:1.5rem; }
-  .var-table th, .instr-table th { background:var(--seafoam); text-align:left;
-       padding:0.4rem 0.6rem; border-bottom:2px solid #cde; }
-  .var-table td, .instr-table td { padding:0.3rem 0.6rem; border-bottom:1px solid #eef; vertical-align:top; }
-  .var-table tr:nth-child(even) td, .instr-table tr:nth-child(even) td { background:#f4f9fc; }
-  .var-table tr:hover td, .instr-table tr:hover td { background:#e8f4f8; }
+  /* .var-table / .instr-table drop to the canonical emit_css table style. */
 {% endblock %}
 {% block masthead_type %}Stacked{% endblock %}
 {% block masthead_meta %}
@@ -84,7 +79,7 @@ <h2 id="instruments">Instruments (deep-first)</h2>
 <!-- Pressure time series -->
 {% if fig_pressure_b64 %}
 <h2 id="pressure">Pressure records (all instruments)</h2>
-<p class="note">Values with QC flag &ge; 3 (suspect/bad) masked to NaN before plotting. All data values are in <code>{{ nc_file }}</code> without masking.</p>
+<p class="caption">Values with QC flag &ge; 3 (suspect/bad) masked to NaN before plotting. All data values are in <code>{{ nc_file }}</code> without masking.</p>
 <img class="fig" src="data:image/png;base64,{{ fig_pressure_b64 }}" alt="Pressure time series">
 {{- m.dbg(fig_pressure_b64, "full (100%)") }}
 {% endif %}
@@ -92,7 +87,7 @@ <h2 id="pressure">Pressure records (all instruments)</h2>
 <!-- Temperature time series -->
 {% if fig_temp_b64 %}
 <h2 id="temp">Temperature (all instruments)</h2>
-<p class="note">Values with QC flag &ge; 3 (suspect/bad) masked to NaN before plotting. All data values are in <code>{{ nc_file }}</code> without masking.</p>
+<p class="caption">Values with QC flag &ge; 3 (suspect/bad) masked to NaN before plotting. All data values are in <code>{{ nc_file }}</code> without masking.</p>
 <img class="fig" src="data:image/png;base64,{{ fig_temp_b64 }}" alt="Temperature time series">
 {{- m.dbg(fig_temp_b64, "full (100%)") }}
 {% endif %}
@@ -100,14 +95,14 @@ <h2 id="temp">Temperature (all instruments)</h2>
 <!-- Salinity time series -->
 {% if fig_sal_b64 %}
 <h2 id="sal">Salinity (all instruments)</h2>
-<p class="note">Values with QC flag &ge; 3 (suspect/bad) masked to NaN before plotting. All data values are in <code>{{ nc_file }}</code> without masking.</p>
+<p class="caption">Values with QC flag &ge; 3 (suspect/bad) masked to NaN before plotting. All data values are in <code>{{ nc_file }}</code> without masking.</p>
 <img class="fig" src="data:image/png;base64,{{ fig_sal_b64 }}" alt="Salinity time series">
 {{- m.dbg(fig_sal_b64, "full (100%)") }}
 {% endif %}
 
 {% if fig_dissolved_oxygen_b64 %}
 <h2 id="dissolved-oxygen">Dissolved oxygen (all instruments)</h2>
-<p class="note">One line per instrument with dissolved oxygen data (SBE ODO sensor); QC flags &ge; 3 masked. Units: µmol L⁻¹. % saturation available in per-instrument reports.</p>
+<p class="caption">One line per instrument with dissolved oxygen data (SBE ODO sensor); QC flags &ge; 3 masked. Units: µmol L⁻¹. % saturation available in per-instrument reports.</p>
 <img class="fig" src="data:image/png;base64,{{ fig_dissolved_oxygen_b64 }}" alt="Dissolved oxygen time series">
 {{- m.dbg(fig_dissolved_oxygen_b64, "full (100%)") }}
 {% endif %}
@@ -115,35 +110,35 @@ <h2 id="dissolved-oxygen">Dissolved oxygen (all instruments)</h2>
 <!-- Velocity time series -->
 {% if fig_east_vel_b64 %}
 <h2 id="vel">East velocity (U)</h2>
-<p class="note">ENU frame. Values with <code>velocity_flag</code> &ge; 3 masked to NaN before plotting. All data values are in <code>{{ nc_file }}</code> without masking. Instruments without velocity data omitted.</p>
+<p class="caption">ENU frame. Values with <code>velocity_flag</code> &ge; 3 masked to NaN before plotting. All data values are in <code>{{ nc_file }}</code> without masking. Instruments without velocity data omitted.</p>
 <img class="fig" src="data:image/png;base64,{{ fig_east_vel_b64 }}" alt="East velocity time series">
 {{- m.dbg(fig_east_vel_b64, "full (100%)") }}
 {% endif %}
 
 {% if fig_north_vel_b64 %}
 <h2>North velocity (V)</h2>
-<p class="note">ENU frame. Values with <code>velocity_flag</code> &ge; 3 masked to NaN before plotting. All data values are in <code>{{ nc_file }}</code> without masking.</p>
+<p class="caption">ENU frame. Values with <code>velocity_flag</code> &ge; 3 masked to NaN before plotting. All data values are in <code>{{ nc_file }}</code> without masking.</p>
 <img class="fig" src="data:image/png;base64,{{ fig_north_vel_b64 }}" alt="North velocity time series">
 {{- m.dbg(fig_north_vel_b64, "full (100%)") }}
 {% endif %}
 
 {% if fig_up_vel_b64 %}
 <h2>Vertical velocity (W)</h2>
-<p class="note">ENU frame. Values with <code>velocity_flag</code> &ge; 3 masked to NaN before plotting. All data values are in <code>{{ nc_file }}</code> without masking.</p>
+<p class="caption">ENU frame. Values with <code>velocity_flag</code> &ge; 3 masked to NaN before plotting. All data values are in <code>{{ nc_file }}</code> without masking.</p>
 <img class="fig" src="data:image/png;base64,{{ fig_up_vel_b64 }}" alt="Vertical velocity time series">
 {{- m.dbg(fig_up_vel_b64, "full (100%)") }}
 {% endif %}
 
 {% if fig_turbidity_b64 %}
 <h2 id="turbidity">Turbidity</h2>
-<p class="note">One line per instrument with turbidity data; QC flags &ge; 3 masked. Dots overlaid to reveal individual samples near zero. Units from file attrs (verify: NTU, FTU, or V depending on sensor).</p>
+<p class="caption">One line per instrument with turbidity data; QC flags &ge; 3 masked. Dots overlaid to reveal individual samples near zero. Units from file attrs (verify: NTU, FTU, or V depending on sensor).</p>
 <img class="fig" src="data:image/png;base64,{{ fig_turbidity_b64 }}" alt="Turbidity time series">
 {{- m.dbg(fig_turbidity_b64, "full (100%)") }}
 {% endif %}
 
 {% if fig_trajectories_b64 or fig_adcp_trajectories_b64 %}
 <h2 id="trajectories">Particle trajectories</h2>
-<p class="note">
+<p class="caption">
   Pseudo-Lagrangian displacement: east/north velocity integrated over time
   (Euler forward; NaN velocities set to zero).  All trajectories share a common origin (0,&nbsp;0).
   Aquadopp: colour shows temperature (shared scale); end points labelled with serial and HAB.
@@ -169,7 +164,7 @@ <h2 id="trajectories">Particle trajectories</h2>
 
 {% if fig_speed_profile_b64 %}
 <h2 id="speed-profile">Aquadopp speed profile</h2>
-<p class="note">
+<p class="caption">
   Horizontal boxplot per Aquadopp, positioned at its nominal height above bottom
   (per-instrument design value; does not account for mooring knockdown).
   Box = interquartile range; line = median; whiskers = 1.5&times;IQR; dots = outliers.
@@ -181,7 +176,7 @@ <h2 id="speed-profile">Aquadopp speed profile</h2>
 
 {% if fig_analog_b64 %}
 <h2 id="analog">Analog channels</h2>
-<p class="note">
+<p class="caption">
   Full-record time series of analog channel variables containing non-zero, non-NaN data.
   One panel per channel.
 </p>
@@ -191,14 +186,14 @@ <h2 id="analog">Analog channels</h2>
 
 {% if fig_ts_stack_b64 %}
 <h2 id="ts">T-S diagram</h2>
-<p class="note">Left: scatter coloured by pressure. Middle: 2-D count heatmap. Right (when oxygen data present): scatter coloured by O₂ saturation (%). Bad (flag&nbsp;4) and missing (flag&nbsp;9) excluded; interpolated pressure (flag&nbsp;8) retained.</p>
+<p class="caption">Left: scatter coloured by pressure. Middle: 2-D count heatmap. Right (when oxygen data present): scatter coloured by O₂ saturation (%). Bad (flag&nbsp;4) and missing (flag&nbsp;9) excluded; interpolated pressure (flag&nbsp;8) retained.</p>
 <img class="fig" src="data:image/png;base64,{{ fig_ts_stack_b64 }}" alt="T-S diagram">
 {{- m.dbg(fig_ts_stack_b64, "full (100%)") }}
 {% endif %}
 
 {% if fig_rose_grid_b64 %}
 <h2 id="roses">Current rose diagrams</h2>
-<p class="note">Direction the current flows toward (oceanographic convention, 0&deg;=N). Speed coloured light&rarr;dark blue (slow&rarr;fast). QC-flagged samples excluded. Title shows serial number and height above bottom (m).</p>
+<p class="caption">Direction the current flows toward (oceanographic convention, 0&deg;=N). Speed coloured light&rarr;dark blue (slow&rarr;fast). QC-flagged samples excluded. Title shows serial number and height above bottom (m).</p>
 {% if rose_declination_warn %}
 <p style="font-size:0.82rem;background:var(--warn-bg);border-left:4px solid var(--warn);padding:0.5rem 0.8rem;margin-bottom:0.6rem;">
   ⚠ Magnetic declination could not be applied to
@@ -208,14 +203,14 @@ <h2 id="roses">Current rose diagrams</h2>
   Affected ENU velocities currently use 0° declination (magnetic north, not true north).
 </p>
 {% endif %}
-{% if rose_declination_note %}<p class="note">{{ rose_declination_note }}</p>{% endif %}
+{% if rose_declination_note %}<p class="caption">{{ rose_declination_note }}</p>{% endif %}
 <img class="fig slot-full" src="data:image/png;base64,{{ fig_rose_grid_b64 }}" alt="Current rose grid">
 {{- m.dbg(fig_rose_grid_b64, "slot-full") }}
 {% endif %}
 
 {% if fig_aquadopp_tilt_b64 %}
 <h2 id="tilt">Aquadopp tilt (|pitch| / |roll| / pressure estimate)</h2>
-<p class="note">
+<p class="caption">
   One panel per Aquadopp (deep-first). Blue = |pitch|, green = |roll|, orange dashed = tilt
   estimated from pressure difference between the Aquadopp and the nearest instrument &ge;10 m above
   with valid pressure (arccos(&Delta;P / rope length)).  All curves are non-negative.
@@ -229,14 +224,14 @@ <h2 id="tilt">Aquadopp tilt (|pitch| / |roll| / pressure estimate)</h2>
 
 {% if fig_spacing_b64 %}
 <h2 id="spacing">Adjacent instrument spacing</h2>
-<p class="note">Distribution of pressure differences between adjacent instrument pairs (pairs &lt; 2 dbar apart excluded as co-located).</p>
+<p class="caption">Distribution of pressure differences between adjacent instrument pairs (pairs &lt; 2 dbar apart excluded as co-located).</p>
 <img style="max-width:33%;border:1px solid var(--rule);border-radius:4px" src="data:image/png;base64,{{ fig_spacing_b64 }}" alt="Instrument spacing histogram">
 {{- m.dbg(fig_spacing_b64, "max-width 33%") }}
 {% endif %}
 
 {% if fig_clock_check_b64 %}
 <h2 id="clock-check">Clock alignment check</h2>
-<p class="note">
+<p class="caption">
   Temperature records from all instruments overlaid, zoomed to the first and last
   10&thinsp;minutes of the deployment.  A horizontal shift between curves indicates
   a clock offset between instruments.  Data are from stage&#8209;3 (or stage&#8209;2
diff --git a/tests/fixtures/golden/dune2/dune2_1_2026_grid_report.html b/tests/fixtures/golden/dune2/dune2_1_2026_grid_report.html
index b74a911..055d3ab 100644
--- a/tests/fixtures/golden/dune2/dune2_1_2026_grid_report.html
+++ b/tests/fixtures/golden/dune2/dune2_1_2026_grid_report.html
@@ -67,15 +67,15 @@
 p, li { max-width: 78ch; }
 .masthead {
   background: var(--ocean); color: #fff; position: relative;
-  padding: 1.6rem 2rem; border-radius: 8px; margin-bottom: 2rem;
+  padding: 1.6rem 2rem; border-radius: var(--radius-card); margin-bottom: 2rem;
 }
 .masthead h1 { margin: 0 0 0.3rem; font-size: var(--fs-h1); font-weight: 700; }
-.masthead .sub { font-size: var(--fs-meta); opacity: 0.85; margin: 0 0 0.15rem; }
+.masthead .sub { font-size: var(--fs-meta); opacity: 0.85; margin: 0 0 0.15rem; max-width: none; }
 .wordmark {
   position: absolute; right: 2rem; bottom: 1.2rem;
   font-size: var(--fs-dt); font-weight: 700; letter-spacing: 0.04em;
   color: var(--package-accent); background: #fff; opacity: 0.85;
-  padding: 0.1rem 0.5rem; border-radius: 999px; text-decoration: none;
+  padding: 0.1rem 0.5rem; border-radius: var(--radius-pill); text-decoration: none;
 }
 .wordmark:hover { opacity: 1; }
 .meta-grid {
@@ -99,10 +99,23 @@
   text-decoration: none; margin-left: auto;
 }
 .top-link:hover { color: var(--ocean); text-decoration: underline; }
-.note {
+.caption {
   color: var(--gray-5); font-size: var(--fs-note);
-  margin-top: -0.5rem; margin-bottom: 0.75rem;
+  margin-top: 0.75rem; margin-bottom: 0.75rem;
 }
+h2 + .caption { margin-top: -0.5rem; }
+.explainer {
+  font-size: var(--fs-note); color: var(--text);
+  background: var(--bg-sunken); border-left: 3px solid var(--muted);
+  padding: var(--sp-3); margin: -0.25rem 0 0.75rem; border-radius: var(--radius-btn);
+}
+.warn {
+  font-size: var(--fs-note); color: var(--text);
+  background: var(--warn-bg); border-left: 3px solid var(--warn);
+  padding: var(--sp-3); margin-bottom: 0.5rem; border-radius: var(--radius-btn);
+}
+.warn::before { content: "⚠ "; }
+.warn.error { border-left-color: var(--error); }
 .jump-nav {
   background: var(--seafoam); padding: 0.55rem 1rem;
   border-radius: 6px; margin-bottom: 1.5rem;
@@ -121,16 +134,33 @@
 .fig-col { display: flex; flex-direction: column; gap: 0.75rem; }
 figure { margin: 0; }
 figure img {
-  border: 1px solid var(--rule); border-radius: 4px;
+  border: 1px solid var(--rule); border-radius: var(--radius-btn);
   display: block; width: 100%; height: auto;
 }
 figcaption { font-size: var(--fs-cap); color: var(--gray-5); margin-top: 0.25rem; }
+table {
+  width: 100%; border-collapse: collapse;
+  font-size: var(--fs-note); margin: 0.6rem 0 1.2rem;
+}
+th {
+  background: var(--package-accent); color: #fff; text-align: left;
+  font-weight: 600; padding: 0.4rem 0.65rem;
+}
+th.num { text-align: right; }
+td {
+  padding: 0.35rem 0.65rem; border-bottom: 1px solid var(--rule);
+  vertical-align: top;
+}
+tr:nth-child(even) td { background: var(--bg-sunken); }
+td.num, .num { text-align: right; font-variant-numeric: tabular-nums; }
+td.mono { font-family: var(--font-mono); font-size: var(--fs-xs); }
 .slot-full         { width: 100%; }
 .slot-twothirds     { width: calc(66.67% - 0.33rem); }
 .slot-three-fifths  { width: calc(60% - 0.40rem); }
 .slot-half          { width: calc(50% - 0.50rem); }
 .slot-two-fifths    { width: calc(40% - 0.60rem); }
 .slot-third         { width: calc(33.33% - 0.67rem); }
+.slot-quarter       { width: calc(25% - 0.75rem); }
 .masthead-header {
   display: flex; justify-content: space-between; align-items: flex-start;
   margin-bottom: 0.3rem;
@@ -143,7 +173,7 @@
 .nav-btns { display: flex; gap: 0.5rem; }
 .btn-nav {
   background: var(--ocean); color: #fff; padding: 0.25rem 0.75rem;
-  border-radius: 999px; text-decoration: none; font-size: var(--fs-nav);
+  border-radius: var(--radius-pill); text-decoration: none; font-size: var(--fs-nav);
 }
 .btn-nav:hover { opacity: 0.85; }
 footer {
@@ -210,8 +240,10 @@
 /* Figures never exceed the content column; the oversampled PNG downscales
    crisply (spec §11 OVERSAMPLE). Pages may override (e.g. array uses 60%). */
 .fig { max-width:100%; height:auto; display:block; }
-td.num { text-align:right; font-variant-numeric:tabular-nums; }
-td.mono { font-family:var(--font-mono); font-size:var(--fs-xs); }
+/* A bare .fig (no slot class) is a full-width figure: fill the column. A
+   slot-* figure gets its width from the .slot-* rule instead — so this must NOT
+   apply to slotted figures (that was the width:100%-overrides-slot bug). */
+.fig:not([class*="slot-"]) { width:100%; }
 .none-note { color:var(--muted); font-style:italic; }
 .var-qc { color:var(--good); font-size:var(--fs-xs); }
 /* Figure-debug line under a plot (OCEANARRAY_REPORT_DEBUG=1): slot the
@@ -231,13 +263,8 @@
      .fig fills via base.html's max-width:100%.  Setting width:100% here would
      override the slot and force every figure full-width (U0.2). */
   .fig { border:1px solid var(--rule); border-radius:var(--radius-btn); margin-bottom:0.5rem; }
-  .note { color:var(--muted); font-size:0.82rem; margin-top:-0.5rem; }
+  /* Table + caption styles are canonical in emit_css now (.var-table drops to the shared table style). */
   .style-label { font-size:0.8rem; font-weight:600; color:var(--muted); margin:0.4rem 0 0.2rem; text-transform:uppercase; letter-spacing:0.05em; }
-  .var-table { width:100%; border-collapse:collapse; font-size:0.82rem; margin-bottom:1.5rem; }
-  .var-table th { background:var(--seafoam); text-align:left; padding:0.4rem 0.6rem; border-bottom:2px solid #cde; }
-  .var-table td { padding:0.3rem 0.6rem; border-bottom:1px solid #eef; vertical-align:top; }
-  .var-table tr:nth-child(even) td { background:#f4f9fc; }
-  .var-table tr:hover td { background:#e8f4f8; }
   details summary.collapse-toggle { color:var(--muted); font-size:0.76rem; cursor:pointer;
     list-style:none; padding:0.15rem 0 0.4rem; user-select:none; }
   details summary.collapse-toggle::before { content:"▾ "; }
@@ -325,7 +352,7 @@ <h2 id="history">Processing history</h2>
 <!-- ══ Hydrography: T and S ══ -->
 
 <h2 id="hydro">Hydrography</h2>
-<p class="note">Temperature, salinity, dissolved oxygen, and O₂ saturation (when present). Vertically interpolated to regular pressure grid &bull; 20 discrete colour levels.</p>
+<p class="caption">Temperature, salinity, dissolved oxygen, and O₂ saturation (when present). Vertically interpolated to regular pressure grid &bull; 20 discrete colour levels.</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,<PNG>" alt="Temperature and salinity">
 </details>
@@ -334,7 +361,7 @@ <h2 id="hydro">Hydrography</h2>
 <!-- ══ Velocity: E / N / Up ══ -->
 
 <h2 id="vel">Velocity</h2>
-<p class="note">East, north, and up velocity. QC-flagged samples excluded before interpolation. Shared symmetric Spectral_r colormap for east/north; separate bounds for up. No temporal gap fill — NaN where no data.</p>
+<p class="caption">East, north, and up velocity. QC-flagged samples excluded before interpolation. Shared symmetric Spectral_r colormap for east/north; separate bounds for up. No temporal gap fill — NaN where no data.</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,<PNG>" alt="Velocity pcolormesh">
 </details>
@@ -343,7 +370,7 @@ <h2 id="vel">Velocity</h2>
 <!-- ══ T-S diagram (before derived quantities) ══ -->
 
 <h2 id="ts">T-S diagram</h2>
-<p class="note">Left: log₁₀(count+1) per T-S bin. Right (when O₂ present): median O₂ saturation per T-S bin — bins with &lt;5 samples masked. Colour scale: BrBG (brown=low, teal=high).</p>
+<p class="caption">Left: log₁₀(count+1) per T-S bin. Right (when O₂ present): median O₂ saturation per T-S bin — bins with &lt;5 samples masked. Colour scale: BrBG (brown=low, teal=high).</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig slot-half" src="data:image/png;base64,<PNG>" alt="T-S diagram">
 </details>
@@ -352,7 +379,7 @@ <h2 id="ts">T-S diagram</h2>
 <!-- ══ Velocity IQR profiles ══ -->
 
 <h2 id="vel-iqr">Velocity IQR profiles</h2>
-<p class="note">Median (solid line) and interquartile range (shaded, 25–75 %) across the full deployment at each pressure level. 2.5–97.5 % outer envelope for speed. Right panel: count of non-NaN values per depth.</p>
+<p class="caption">Median (solid line) and interquartile range (shaded, 25–75 %) across the full deployment at each pressure level. 2.5–97.5 % outer envelope for speed. Right panel: count of non-NaN values per depth.</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,<PNG>" alt="Velocity IQR profiles">
 </details>
@@ -361,7 +388,7 @@ <h2 id="vel-iqr">Velocity IQR profiles</h2>
 <!-- ══ Current roses per pressure level ══ -->
 
 <h2 id="grid-rose">Current roses</h2>
-<p class="note">One rose per pressure level (up to 12, evenly subsampled). Suspect/bad QC excluded. Each petal shows the fraction of time current flowed in that direction; petal length encodes speed (m s⁻¹).</p>
+<p class="caption">One rose per pressure level (up to 12, evenly subsampled). Suspect/bad QC excluded. Each petal shows the fraction of time current flowed in that direction; petal length encodes speed (m s⁻¹).</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,<PNG>" alt="Current roses by pressure level">
 </details>
@@ -370,7 +397,7 @@ <h2 id="grid-rose">Current roses</h2>
 <!-- ══ Hodograph ══ -->
 
 <h2 id="grid-hodograph">Hodograph</h2>
-<p class="note">Current hodographs at two pressure levels (25th and 75th percentile of the valid range). Top row = shallower level; bottom row = deeper level. Left = Tukey-smoothed raw; right = eddy component (LP mean removed). Colour indicates fractional time through the deployment (lime circle = start, red square = end). QC-bad data excluded.</p>
+<p class="caption">Current hodographs at two pressure levels (25th and 75th percentile of the valid range). Top row = shallower level; bottom row = deeper level. Left = Tukey-smoothed raw; right = eddy component (LP mean removed). Colour indicates fractional time through the deployment (lime circle = start, red square = end). QC-bad data excluded.</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,<PNG>" alt="Hodograph at two pressure levels">
 </details>
@@ -379,7 +406,7 @@ <h2 id="grid-hodograph">Hodograph</h2>
 <!-- ══ Particle trajectory ══ -->
 
 <h2 id="grid-traj">Particle trajectory</h2>
-<p class="note">Pseudo-Lagrangian trajectories at each gridded pressure level, integrated from east and north velocity (Euler forward). All start at the origin. Coloured by pressure (dbar).</p>
+<p class="caption">Pseudo-Lagrangian trajectories at each gridded pressure level, integrated from east and north velocity (Euler forward). All start at the origin. Coloured by pressure (dbar).</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig slot-half" src="data:image/png;base64,<PNG>" alt="Grid particle trajectory">
 </details>
@@ -388,7 +415,7 @@ <h2 id="grid-traj">Particle trajectory</h2>
 <!-- ══ Velocity time series at depth of max speed ══ -->
 
 <h2 id="grid-ts">Velocity time series at depth of maximum mean speed</h2>
-<p class="note">Depth chosen as the pressure level with the highest time-mean current speed. Speed, east, and north velocity at that level.</p>
+<p class="caption">Depth chosen as the pressure level with the highest time-mean current speed. Speed, east, and north velocity at that level.</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,<PNG>" alt="Velocity time series at max-speed depth">
 </details>
@@ -400,7 +427,7 @@ <h2 id="strat">Stratification</h2>
 
 
 
-<p class="note">Potential density. 20 discrete colour levels.</p>
+<p class="caption">Potential density. 20 discrete colour levels.</p>
 <details open><summary class="collapse-toggle">show / hide sigma0</summary>
 <img class="fig" src="data:image/png;base64,<PNG>" alt="Potential density pcolormesh">
 </details>
@@ -408,7 +435,7 @@ <h2 id="strat">Stratification</h2>
 
 
 <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;">Buoyancy frequency squared (N²)</h3>
-<p class="note">log₁₀(N²) in s⁻². Purple = strongly stratified; yellow = weakly stratified. Computed from T and S via GSW.</p>
+<p class="caption">log₁₀(N²) in s⁻². Purple = strongly stratified; yellow = weakly stratified. Computed from T and S via GSW.</p>
 <details open><summary class="collapse-toggle">show / hide N²</summary>
 <img class="fig" src="data:image/png;base64,<PNG>" alt="N² pcolormesh">
 </details>
@@ -420,7 +447,7 @@ <h2 id="overflow">Overflow</h2>
 
 
 <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;">Isopycnal coverage diagnostic</h3>
-<p class="note">Percentage of time steps during which each σ₀ surface (0.1&nbsp;kg&nbsp;m⁻³ spacing) lies within the measured column range. Green&nbsp;≥&nbsp;80&nbsp;%; amber&nbsp;50–80&nbsp;%; red&nbsp;&lt;&nbsp;50&nbsp;%. Orange diamond&nbsp;= current <code>--sig-level</code> target. Dashed line&nbsp;=&nbsp;80&nbsp;% threshold. NaN gaps in the tracking figure above correspond to times when the isopycnal is outside the measured range (pycnocline above the shallowest grid level, or below the deepest).</p>
+<p class="caption">Percentage of time steps during which each σ₀ surface (0.1&nbsp;kg&nbsp;m⁻³ spacing) lies within the measured column range. Green&nbsp;≥&nbsp;80&nbsp;%; amber&nbsp;50–80&nbsp;%; red&nbsp;&lt;&nbsp;50&nbsp;%. Orange diamond&nbsp;= current <code>--sig-level</code> target. Dashed line&nbsp;=&nbsp;80&nbsp;% threshold. NaN gaps in the tracking figure above correspond to times when the isopycnal is outside the measured range (pycnocline above the shallowest grid level, or below the deepest).</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,<PNG>" alt="Isopycnal coverage diagnostic">
 </details>
@@ -429,7 +456,7 @@ <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;">Isopycna
 
 
 <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;">Isopycnal height above seabed &mdash; sigma0</h3>
-<p class="note">Height above seabed (m) of each target σ₀ surface through time. Tracked by linear interpolation in density space from the gridded sigma0 field; 1-hour running median applied. NaN where the surface outcrops or is outside the observed range. Light blue = lighter water (shallower); dark blue = denser water (deeper). Targets set by <code>--sig-level</code> (default σ₀&nbsp;=&nbsp;27.70).</p>
+<p class="caption">Height above seabed (m) of each target σ₀ surface through time. Tracked by linear interpolation in density space from the gridded sigma0 field; 1-hour running median applied. NaN where the surface outcrops or is outside the observed range. Light blue = lighter water (shallower); dark blue = denser water (deeper). Targets set by <code>--sig-level</code> (default σ₀&nbsp;=&nbsp;27.70).</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,<PNG>" alt="Isopycnal height above seabed">
 </details>
@@ -438,7 +465,7 @@ <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;">Isopycna
 
 
 <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;">Temperature ~100 m above seabed</h3>
-<p class="note">1-hour running median temperature at the grid pressure level nearest to 100&nbsp;m above the seabed. Level and height-above-seabed shown in figure title.</p>
+<p class="caption">1-hour running median temperature at the grid pressure level nearest to 100&nbsp;m above the seabed. Level and height-above-seabed shown in figure title.</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,<PNG>" alt="Temperature near seabed">
 </details>
@@ -446,7 +473,7 @@ <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;">Temperat
 
 
 <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;" id="spectrum">Temperature power spectrum</h3>
-<p class="note"><strong>Left:</strong> low-frequency overview — 14-day Hann windows, 50&nbsp;% overlap. <strong>Right:</strong> high-frequency zoom — 1-day windows (~14&times; more windows, smoother tidal/inertial estimate); x-axis in hours. LF markers: M2, 1.8&nbsp;d, 4&nbsp;d, f. HF markers: M2 (12.4&nbsp;h), f (inertial). Dashed black line: &minus;2 spectral slope. Colour encodes pressure (light blue = shallow, dark blue = deep). Window length controllable via <code>hf_segment_days</code> in <code>_make_spectrum_fig_b64</code>.</p>
+<p class="caption"><strong>Left:</strong> low-frequency overview — 14-day Hann windows, 50&nbsp;% overlap. <strong>Right:</strong> high-frequency zoom — 1-day windows (~14&times; more windows, smoother tidal/inertial estimate); x-axis in hours. LF markers: M2, 1.8&nbsp;d, 4&nbsp;d, f. HF markers: M2 (12.4&nbsp;h), f (inertial). Dashed black line: &minus;2 spectral slope. Colour encodes pressure (light blue = shallow, dark blue = deep). Window length controllable via <code>hf_segment_days</code> in <code>_make_spectrum_fig_b64</code>.</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,<PNG>" alt="Temperature power spectrum">
 </details>
@@ -454,7 +481,7 @@ <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;" id="spec
 
 
 <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;" id="wavelet">Temperature wavelet scalogram</h3>
-<p class="note">Continuous wavelet transform (Morlet, &omega;<sub>0</sub>&nbsp;=&nbsp;6; Torrence &amp; Compo 1998).  Three depth levels: 2nd from top, middle, 2nd from bottom of the 100-dbar-multiple valid levels.  Colour shows log<sub>10</sub>(power) (°C²&nbsp;d); hatched grey region = cone of influence (edge-affected); hatched cross region = gap-filled data; black contour = 95&nbsp;% significance against red noise.</p>
+<p class="caption">Continuous wavelet transform (Morlet, &omega;<sub>0</sub>&nbsp;=&nbsp;6; Torrence &amp; Compo 1998).  Three depth levels: 2nd from top, middle, 2nd from bottom of the 100-dbar-multiple valid levels.  Colour shows log<sub>10</sub>(power) (°C²&nbsp;d); hatched grey region = cone of influence (edge-affected); hatched cross region = gap-filled data; black contour = 95&nbsp;% significance against red noise.</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,<PNG>" alt="Temperature wavelet scalogram">
 </details>
@@ -462,7 +489,7 @@ <h3 style="font-size:0.9rem;color:var(--ocean);margin:1.5rem 0 0.4rem;" id="wave
 
 
 <h2 id="rotary">Rotary velocity spectrum</h2>
-<p class="note">CW (clockwise, anticyclonic, solid red lines) and CCW (counter-clockwise, cyclonic, dashed blue lines) power spectra and rotary coefficient r&nbsp;=&nbsp;(CCW&minus;CW)/(CCW+CW). Welch PSD, Hann window, 14-day segments, 50&nbsp;% overlap. Up to 4 pressure levels (at most 1/5th of valid levels); colour encodes pressure depth. Vertical lines: M2, K1, 1.8&nbsp;d, 4&nbsp;d, and inertial period (f). r&nbsp;&gt;&nbsp;0&nbsp;=&nbsp;CCW dominant; r&nbsp;&lt;&nbsp;0&nbsp;=&nbsp;CW dominant. Physical interpretation (NH): inertial oscillations are inherently CW; for internal waves (f&nbsp;&lt;&nbsp;&omega;), CW dominance indicates upward energy propagation / downward phase propagation (Leaman &amp; Sanford 1975).</p>
+<p class="caption">CW (clockwise, anticyclonic, solid red lines) and CCW (counter-clockwise, cyclonic, dashed blue lines) power spectra and rotary coefficient r&nbsp;=&nbsp;(CCW&minus;CW)/(CCW+CW). Welch PSD, Hann window, 14-day segments, 50&nbsp;% overlap. Up to 4 pressure levels (at most 1/5th of valid levels); colour encodes pressure depth. Vertical lines: M2, K1, 1.8&nbsp;d, 4&nbsp;d, and inertial period (f). r&nbsp;&gt;&nbsp;0&nbsp;=&nbsp;CCW dominant; r&nbsp;&lt;&nbsp;0&nbsp;=&nbsp;CW dominant. Physical interpretation (NH): inertial oscillations are inherently CW; for internal waves (f&nbsp;&lt;&nbsp;&omega;), CW dominance indicates upward energy propagation / downward phase propagation (Leaman &amp; Sanford 1975).</p>
 <details open><summary class="collapse-toggle">show / hide</summary>
 <img class="fig" src="data:image/png;base64,<PNG>" alt="Rotary velocity spectrum">
 </details>
diff --git a/tests/fixtures/golden/dune2/dune2_1_2026_report.html b/tests/fixtures/golden/dune2/dune2_1_2026_report.html
index a5ed590..519f8ef 100644
--- a/tests/fixtures/golden/dune2/dune2_1_2026_report.html
+++ b/tests/fixtures/golden/dune2/dune2_1_2026_report.html
@@ -67,15 +67,15 @@
 p, li { max-width: 78ch; }
 .masthead {
   background: var(--ocean); color: #fff; position: relative;
-  padding: 1.6rem 2rem; border-radius: 8px; margin-bottom: 2rem;
+  padding: 1.6rem 2rem; border-radius: var(--radius-card); margin-bottom: 2rem;
 }
 .masthead h1 { margin: 0 0 0.3rem; font-size: var(--fs-h1); font-weight: 700; }
-.masthead .sub { font-size: var(--fs-meta); opacity: 0.85; margin: 0 0 0.15rem; }
+.masthead .sub { font-size: var(--fs-meta); opacity: 0.85; margin: 0 0 0.15rem; max-width: none; }
 .wordmark {
   position: absolute; right: 2rem; bottom: 1.2rem;
   font-size: var(--fs-dt); font-weight: 700; letter-spacing: 0.04em;
   color: var(--package-accent); background: #fff; opacity: 0.85;
-  padding: 0.1rem 0.5rem; border-radius: 999px; text-decoration: none;
+  padding: 0.1rem 0.5rem; border-radius: var(--radius-pill); text-decoration: none;
 }
 .wordmark:hover { opacity: 1; }
 .meta-grid {
@@ -99,10 +99,23 @@
   text-decoration: none; margin-left: auto;
 }
 .top-link:hover { color: var(--ocean); text-decoration: underline; }
-.note {
+.caption {
   color: var(--gray-5); font-size: var(--fs-note);
-  margin-top: -0.5rem; margin-bottom: 0.75rem;
+  margin-top: 0.75rem; margin-bottom: 0.75rem;
 }
+h2 + .caption { margin-top: -0.5rem; }
+.explainer {
+  font-size: var(--fs-note); color: var(--text);
+  background: var(--bg-sunken); border-left: 3px solid var(--muted);
+  padding: var(--sp-3); margin: -0.25rem 0 0.75rem; border-radius: var(--radius-btn);
+}
+.warn {
+  font-size: var(--fs-note); color: var(--text);
+  background: var(--warn-bg); border-left: 3px solid var(--warn);
+  padding: var(--sp-3); margin-bottom: 0.5rem; border-radius: var(--radius-btn);
+}
+.warn::before { content: "⚠ "; }
+.warn.error { border-left-color: var(--error); }
 .jump-nav {
   background: var(--seafoam); padding: 0.55rem 1rem;
   border-radius: 6px; margin-bottom: 1.5rem;
@@ -121,16 +134,33 @@
 .fig-col { display: flex; flex-direction: column; gap: 0.75rem; }
 figure { margin: 0; }
 figure img {
-  border: 1px solid var(--rule); border-radius: 4px;
+  border: 1px solid var(--rule); border-radius: var(--radius-btn);
   display: block; width: 100%; height: auto;
 }
 figcaption { font-size: var(--fs-cap); color: var(--gray-5); margin-top: 0.25rem; }
+table {
+  width: 100%; border-collapse: collapse;
+  font-size: var(--fs-note); margin: 0.6rem 0 1.2rem;
+}
+th {
+  background: var(--package-accent); color: #fff; text-align: left;
+  font-weight: 600; padding: 0.4rem 0.65rem;
+}
+th.num { text-align: right; }
+td {
+  padding: 0.35rem 0.65rem; border-bottom: 1px solid var(--rule);
+  vertical-align: top;
+}
+tr:nth-child(even) td { background: var(--bg-sunken); }
+td.num, .num { text-align: right; font-variant-numeric: tabular-nums; }
+td.mono { font-family: var(--font-mono); font-size: var(--fs-xs); }
 .slot-full         { width: 100%; }
 .slot-twothirds     { width: calc(66.67% - 0.33rem); }
 .slot-three-fifths  { width: calc(60% - 0.40rem); }
 .slot-half          { width: calc(50% - 0.50rem); }
 .slot-two-fifths    { width: calc(40% - 0.60rem); }
 .slot-third         { width: calc(33.33% - 0.67rem); }
+.slot-quarter       { width: calc(25% - 0.75rem); }
 .masthead-header {
   display: flex; justify-content: space-between; align-items: flex-start;
   margin-bottom: 0.3rem;
@@ -143,7 +173,7 @@
 .nav-btns { display: flex; gap: 0.5rem; }
 .btn-nav {
   background: var(--ocean); color: #fff; padding: 0.25rem 0.75rem;
-  border-radius: 999px; text-decoration: none; font-size: var(--fs-nav);
+  border-radius: var(--radius-pill); text-decoration: none; font-size: var(--fs-nav);
 }
 .btn-nav:hover { opacity: 0.85; }
 footer {
@@ -210,8 +240,10 @@
 /* Figures never exceed the content column; the oversampled PNG downscales
    crisply (spec §11 OVERSAMPLE). Pages may override (e.g. array uses 60%). */
 .fig { max-width:100%; height:auto; display:block; }
-td.num { text-align:right; font-variant-numeric:tabular-nums; }
-td.mono { font-family:var(--font-mono); font-size:var(--fs-xs); }
+/* A bare .fig (no slot class) is a full-width figure: fill the column. A
+   slot-* figure gets its width from the .slot-* rule instead — so this must NOT
+   apply to slotted figures (that was the width:100%-overrides-slot bug). */
+.fig:not([class*="slot-"]) { width:100%; }
 .none-note { color:var(--muted); font-style:italic; }
 .var-qc { color:var(--good); font-size:var(--fs-xs); }
 /* Figure-debug line under a plot (OCEANARRAY_REPORT_DEBUG=1): slot the
@@ -226,18 +258,8 @@
   .masthead, th { -webkit-print-color-adjust:exact; print-color-adjust:exact; }
 }
 
-  table { width: 100%; border-collapse: collapse; font-size: 0.83rem; }
-  th {
-    background: var(--ocean);
-    color: #fff;
-    padding: 0.45rem 0.7rem;
-    text-align: left;
-    font-weight: 600;
-    white-space: nowrap;
-  }
-  td { padding: 0.38rem 0.7rem; border-bottom: 1px solid #ecf0f1; vertical-align: middle; }
-  tr:nth-child(even) td { background: var(--seafoam); }
-  tr:hover td { background: #d6eaf8; }
+  /* Table style is now canonical in emit_css (shared).  Only page-specific
+     content styles remain here. */
   .pipeline { white-space: nowrap; display: flex; flex-wrap: wrap; gap: 0.2rem; align-items: center; }
   .badge {
     display: inline-block;
@@ -839,7 +861,7 @@ <h2 id="clock">4 &mdash; Clock corrections</h2>
 
 
 <h3 style="font-size:0.9rem;margin-top:1.2rem;">Clock alignment check</h3>
-<p class="note">
+<p class="caption">
   Overlaid temperature records zoomed to the first and last 30 minutes of the deployment.
   If instrument clocks are misaligned the temperature curves will appear shifted in time.
   Data are from stage&#8209;3 (or stage&#8209;2 if stage&#8209;3 is not yet available).
@@ -1508,7 +1530,7 @@ <h2 id="knockdown">Mooring knockdown</h2>
 <div style="display:flex;gap:1rem;flex-wrap:wrap;align-items:flex-start">
 
 <div style="flex:1;min-width:260px">
-<p class="note">Nominal HAB (x) vs. measured pressure (y). The dashed line shows expected pressure
+<p class="caption">Nominal HAB (x) vs. measured pressure (y). The dashed line shows expected pressure
   (water&nbsp;depth&nbsp;&minus;&nbsp;HAB). Instruments below the line were knocked down.
   Interpolated pressure (QC&nbsp;flag&nbsp;8) excluded.</p>
 <img style="width:100%;border:1px solid var(--rule);border-radius:4px" src="data:image/png;base64,<PNG>" alt="Knockdown HAB vs pressure">
@@ -1516,7 +1538,7 @@ <h2 id="knockdown">Mooring knockdown</h2>
 
 
 <div style="flex:1;min-width:260px">
-<p class="note">IQR of pressure anomaly (measured &minus; nominal) per instrument.
+<p class="caption">IQR of pressure anomaly (measured &minus; nominal) per instrument.
   Positive = deeper than design depth.
   <span style="color:mediumseagreen">Green</span> &lt;&nbsp;100&nbsp;dbar,
   <span style="color:goldenrod">yellow</span> 100–200,
@@ -1527,11 +1549,11 @@ <h2 id="knockdown">Mooring knockdown</h2>
 
 </div>
 
-<p class="note">Estimated horizontal displacement (m) vs. measured pressure.
+<p class="caption">Estimated horizontal displacement (m) vs. measured pressure.
   Left: scatter per instrument; right: normalised 2-D density across all instruments.
   Displacement derived from the rigid-pendulum approximation:
   <em>x</em>&nbsp;=&nbsp;&radic;(hab<sub>nom</sub>&sup2;&nbsp;&minus;&nbsp;hab<sub>meas</sub>&sup2;).</p>
-<img style="width:100%;border:1px solid var(--rule);border-radius:4px" src="data:image/png;base64,<PNG>" alt="Knockdown horizontal displacement">
+<img class="fig slot-full" style="border:1px solid var(--rule);border-radius:4px" src="data:image/png;base64,<PNG>" alt="Knockdown horizontal displacement">
 
 
 
diff --git a/tests/fixtures/golden/dune2/dune2_1_2026_stack_report.html b/tests/fixtures/golden/dune2/dune2_1_2026_stack_report.html
index 3e1c690..b21decd 100644
--- a/tests/fixtures/golden/dune2/dune2_1_2026_stack_report.html
+++ b/tests/fixtures/golden/dune2/dune2_1_2026_stack_report.html
@@ -67,15 +67,15 @@
 p, li { max-width: 78ch; }
 .masthead {
   background: var(--ocean); color: #fff; position: relative;
-  padding: 1.6rem 2rem; border-radius: 8px; margin-bottom: 2rem;
+  padding: 1.6rem 2rem; border-radius: var(--radius-card); margin-bottom: 2rem;
 }
 .masthead h1 { margin: 0 0 0.3rem; font-size: var(--fs-h1); font-weight: 700; }
-.masthead .sub { font-size: var(--fs-meta); opacity: 0.85; margin: 0 0 0.15rem; }
+.masthead .sub { font-size: var(--fs-meta); opacity: 0.85; margin: 0 0 0.15rem; max-width: none; }
 .wordmark {
   position: absolute; right: 2rem; bottom: 1.2rem;
   font-size: var(--fs-dt); font-weight: 700; letter-spacing: 0.04em;
   color: var(--package-accent); background: #fff; opacity: 0.85;
-  padding: 0.1rem 0.5rem; border-radius: 999px; text-decoration: none;
+  padding: 0.1rem 0.5rem; border-radius: var(--radius-pill); text-decoration: none;
 }
 .wordmark:hover { opacity: 1; }
 .meta-grid {
@@ -99,10 +99,23 @@
   text-decoration: none; margin-left: auto;
 }
 .top-link:hover { color: var(--ocean); text-decoration: underline; }
-.note {
+.caption {
   color: var(--gray-5); font-size: var(--fs-note);
-  margin-top: -0.5rem; margin-bottom: 0.75rem;
+  margin-top: 0.75rem; margin-bottom: 0.75rem;
 }
+h2 + .caption { margin-top: -0.5rem; }
+.explainer {
+  font-size: var(--fs-note); color: var(--text);
+  background: var(--bg-sunken); border-left: 3px solid var(--muted);
+  padding: var(--sp-3); margin: -0.25rem 0 0.75rem; border-radius: var(--radius-btn);
+}
+.warn {
+  font-size: var(--fs-note); color: var(--text);
+  background: var(--warn-bg); border-left: 3px solid var(--warn);
+  padding: var(--sp-3); margin-bottom: 0.5rem; border-radius: var(--radius-btn);
+}
+.warn::before { content: "⚠ "; }
+.warn.error { border-left-color: var(--error); }
 .jump-nav {
   background: var(--seafoam); padding: 0.55rem 1rem;
   border-radius: 6px; margin-bottom: 1.5rem;
@@ -121,16 +134,33 @@
 .fig-col { display: flex; flex-direction: column; gap: 0.75rem; }
 figure { margin: 0; }
 figure img {
-  border: 1px solid var(--rule); border-radius: 4px;
+  border: 1px solid var(--rule); border-radius: var(--radius-btn);
   display: block; width: 100%; height: auto;
 }
 figcaption { font-size: var(--fs-cap); color: var(--gray-5); margin-top: 0.25rem; }
+table {
+  width: 100%; border-collapse: collapse;
+  font-size: var(--fs-note); margin: 0.6rem 0 1.2rem;
+}
+th {
+  background: var(--package-accent); color: #fff; text-align: left;
+  font-weight: 600; padding: 0.4rem 0.65rem;
+}
+th.num { text-align: right; }
+td {
+  padding: 0.35rem 0.65rem; border-bottom: 1px solid var(--rule);
+  vertical-align: top;
+}
+tr:nth-child(even) td { background: var(--bg-sunken); }
+td.num, .num { text-align: right; font-variant-numeric: tabular-nums; }
+td.mono { font-family: var(--font-mono); font-size: var(--fs-xs); }
 .slot-full         { width: 100%; }
 .slot-twothirds     { width: calc(66.67% - 0.33rem); }
 .slot-three-fifths  { width: calc(60% - 0.40rem); }
 .slot-half          { width: calc(50% - 0.50rem); }
 .slot-two-fifths    { width: calc(40% - 0.60rem); }
 .slot-third         { width: calc(33.33% - 0.67rem); }
+.slot-quarter       { width: calc(25% - 0.75rem); }
 .masthead-header {
   display: flex; justify-content: space-between; align-items: flex-start;
   margin-bottom: 0.3rem;
@@ -143,7 +173,7 @@
 .nav-btns { display: flex; gap: 0.5rem; }
 .btn-nav {
   background: var(--ocean); color: #fff; padding: 0.25rem 0.75rem;
-  border-radius: 999px; text-decoration: none; font-size: var(--fs-nav);
+  border-radius: var(--radius-pill); text-decoration: none; font-size: var(--fs-nav);
 }
 .btn-nav:hover { opacity: 0.85; }
 footer {
@@ -210,8 +240,10 @@
 /* Figures never exceed the content column; the oversampled PNG downscales
    crisply (spec §11 OVERSAMPLE). Pages may override (e.g. array uses 60%). */
 .fig { max-width:100%; height:auto; display:block; }
-td.num { text-align:right; font-variant-numeric:tabular-nums; }
-td.mono { font-family:var(--font-mono); font-size:var(--fs-xs); }
+/* A bare .fig (no slot class) is a full-width figure: fill the column. A
+   slot-* figure gets its width from the .slot-* rule instead — so this must NOT
+   apply to slotted figures (that was the width:100%-overrides-slot bug). */
+.fig:not([class*="slot-"]) { width:100%; }
 .none-note { color:var(--muted); font-style:italic; }
 .var-qc { color:var(--good); font-size:var(--fs-xs); }
 /* Figure-debug line under a plot (OCEANARRAY_REPORT_DEBUG=1): slot the
@@ -230,12 +262,7 @@
   /* No width here: the slot class sets each figure's width (U0.2); width:100%
      would override the slot and force full-width. */
   .fig { border:1px solid var(--rule); border-radius:var(--radius-btn); margin-bottom:1.5rem; }
-  .var-table, .instr-table { width:100%; border-collapse:collapse; font-size:0.82rem; margin-bottom:1.5rem; }
-  .var-table th, .instr-table th { background:var(--seafoam); text-align:left;
-       padding:0.4rem 0.6rem; border-bottom:2px solid #cde; }
-  .var-table td, .instr-table td { padding:0.3rem 0.6rem; border-bottom:1px solid #eef; vertical-align:top; }
-  .var-table tr:nth-child(even) td, .instr-table tr:nth-child(even) td { background:#f4f9fc; }
-  .var-table tr:hover td, .instr-table tr:hover td { background:#e8f4f8; }
+  /* .var-table / .instr-table drop to the canonical emit_css table style. */
 
 </style>
 
@@ -494,21 +521,21 @@ <h2 id="instruments">Instruments (deep-first)</h2>
 <!-- Pressure time series -->
 
 <h2 id="pressure">Pressure records (all instruments)</h2>
-<p class="note">Values with QC flag &ge; 3 (suspect/bad) masked to NaN before plotting. All data values are in <code>dune2_1_2026_stack.nc</code> without masking.</p>
+<p class="caption">Values with QC flag &ge; 3 (suspect/bad) masked to NaN before plotting. All data values are in <code>dune2_1_2026_stack.nc</code> without masking.</p>
 <img class="fig" src="data:image/png;base64,<PNG>" alt="Pressure time series">
 
 
 <!-- Temperature time series -->
 
 <h2 id="temp">Temperature (all instruments)</h2>
-<p class="note">Values with QC flag &ge; 3 (suspect/bad) masked to NaN before plotting. All data values are in <code>dune2_1_2026_stack.nc</code> without masking.</p>
+<p class="caption">Values with QC flag &ge; 3 (suspect/bad) masked to NaN before plotting. All data values are in <code>dune2_1_2026_stack.nc</code> without masking.</p>
 <img class="fig" src="data:image/png;base64,<PNG>" alt="Temperature time series">
 
 
 <!-- Salinity time series -->
 
 <h2 id="sal">Salinity (all instruments)</h2>
-<p class="note">Values with QC flag &ge; 3 (suspect/bad) masked to NaN before plotting. All data values are in <code>dune2_1_2026_stack.nc</code> without masking.</p>
+<p class="caption">Values with QC flag &ge; 3 (suspect/bad) masked to NaN before plotting. All data values are in <code>dune2_1_2026_stack.nc</code> without masking.</p>
 <img class="fig" src="data:image/png;base64,<PNG>" alt="Salinity time series">
 
 
@@ -517,19 +544,19 @@ <h2 id="sal">Salinity (all instruments)</h2>
 <!-- Velocity time series -->
 
 <h2 id="vel">East velocity (U)</h2>
-<p class="note">ENU frame. Values with <code>velocity_flag</code> &ge; 3 masked to NaN before plotting. All data values are in <code>dune2_1_2026_stack.nc</code> without masking. Instruments without velocity data omitted.</p>
+<p class="caption">ENU frame. Values with <code>velocity_flag</code> &ge; 3 masked to NaN before plotting. All data values are in <code>dune2_1_2026_stack.nc</code> without masking. Instruments without velocity data omitted.</p>
 <img class="fig" src="data:image/png;base64,<PNG>" alt="East velocity time series">
 
 
 
 <h2>North velocity (V)</h2>
-<p class="note">ENU frame. Values with <code>velocity_flag</code> &ge; 3 masked to NaN before plotting. All data values are in <code>dune2_1_2026_stack.nc</code> without masking.</p>
+<p class="caption">ENU frame. Values with <code>velocity_flag</code> &ge; 3 masked to NaN before plotting. All data values are in <code>dune2_1_2026_stack.nc</code> without masking.</p>
 <img class="fig" src="data:image/png;base64,<PNG>" alt="North velocity time series">
 
 
 
 <h2>Vertical velocity (W)</h2>
-<p class="note">ENU frame. Values with <code>velocity_flag</code> &ge; 3 masked to NaN before plotting. All data values are in <code>dune2_1_2026_stack.nc</code> without masking.</p>
+<p class="caption">ENU frame. Values with <code>velocity_flag</code> &ge; 3 masked to NaN before plotting. All data values are in <code>dune2_1_2026_stack.nc</code> without masking.</p>
 <img class="fig" src="data:image/png;base64,<PNG>" alt="Vertical velocity time series">
 
 
@@ -537,7 +564,7 @@ <h2>Vertical velocity (W)</h2>
 
 
 <h2 id="trajectories">Particle trajectories</h2>
-<p class="note">
+<p class="caption">
   Pseudo-Lagrangian displacement: east/north velocity integrated over time
   (Euler forward; NaN velocities set to zero).  All trajectories share a common origin (0,&nbsp;0).
   Aquadopp: colour shows temperature (shared scale); end points labelled with serial and HAB.
@@ -556,7 +583,7 @@ <h2 id="trajectories">Particle trajectories</h2>
 
 
 <h2 id="speed-profile">Aquadopp speed profile</h2>
-<p class="note">
+<p class="caption">
   Horizontal boxplot per Aquadopp, positioned at its nominal height above bottom
   (per-instrument design value; does not account for mooring knockdown).
   Box = interquartile range; line = median; whiskers = 1.5&times;IQR; dots = outliers.
@@ -569,21 +596,21 @@ <h2 id="speed-profile">Aquadopp speed profile</h2>
 
 
 <h2 id="ts">T-S diagram</h2>
-<p class="note">Left: scatter coloured by pressure. Middle: 2-D count heatmap. Right (when oxygen data present): scatter coloured by O₂ saturation (%). Bad (flag&nbsp;4) and missing (flag&nbsp;9) excluded; interpolated pressure (flag&nbsp;8) retained.</p>
+<p class="caption">Left: scatter coloured by pressure. Middle: 2-D count heatmap. Right (when oxygen data present): scatter coloured by O₂ saturation (%). Bad (flag&nbsp;4) and missing (flag&nbsp;9) excluded; interpolated pressure (flag&nbsp;8) retained.</p>
 <img class="fig" src="data:image/png;base64,<PNG>" alt="T-S diagram">
 
 
 
 <h2 id="roses">Current rose diagrams</h2>
-<p class="note">Direction the current flows toward (oceanographic convention, 0&deg;=N). Speed coloured light&rarr;dark blue (slow&rarr;fast). QC-flagged samples excluded. Title shows serial number and height above bottom (m).</p>
+<p class="caption">Direction the current flows toward (oceanographic convention, 0&deg;=N). Speed coloured light&rarr;dark blue (slow&rarr;fast). QC-flagged samples excluded. Title shows serial number and height above bottom (m).</p>
 
-<p class="note">Magnetic declination applied: -13.97°</p>
+<p class="caption">Magnetic declination applied: -13.97°</p>
 <img class="fig slot-full" src="data:image/png;base64,<PNG>" alt="Current rose grid">
 
 
 
 <h2 id="tilt">Aquadopp tilt (|pitch| / |roll| / pressure estimate)</h2>
-<p class="note">
+<p class="caption">
   One panel per Aquadopp (deep-first). Blue = |pitch|, green = |roll|, orange dashed = tilt
   estimated from pressure difference between the Aquadopp and the nearest instrument &ge;10 m above
   with valid pressure (arccos(&Delta;P / rope length)).  All curves are non-negative.
@@ -596,13 +623,13 @@ <h2 id="tilt">Aquadopp tilt (|pitch| / |roll| / pressure estimate)</h2>
 
 
 <h2 id="spacing">Adjacent instrument spacing</h2>
-<p class="note">Distribution of pressure differences between adjacent instrument pairs (pairs &lt; 2 dbar apart excluded as co-located).</p>
+<p class="caption">Distribution of pressure differences between adjacent instrument pairs (pairs &lt; 2 dbar apart excluded as co-located).</p>
 <img style="max-width:33%;border:1px solid var(--rule);border-radius:4px" src="data:image/png;base64,<PNG>" alt="Instrument spacing histogram">
 
 
 
 <h2 id="clock-check">Clock alignment check</h2>
-<p class="note">
+<p class="caption">
   Temperature records from all instruments overlaid, zoomed to the first and last
   10&thinsp;minutes of the deployment.  A horizontal shift between curves indicates
   a clock offset between instruments.  Data are from stage&#8209;3 (or stage&#8209;2
diff --git a/tests/fixtures/golden/dune2/instrument/dune2_1_2026_2941_report.html b/tests/fixtures/golden/dune2/instrument/dune2_1_2026_2941_report.html
index 2e04e46..248938e 100644
--- a/tests/fixtures/golden/dune2/instrument/dune2_1_2026_2941_report.html
+++ b/tests/fixtures/golden/dune2/instrument/dune2_1_2026_2941_report.html
@@ -67,15 +67,15 @@
 p, li { max-width: 78ch; }
 .masthead {
   background: var(--ocean); color: #fff; position: relative;
-  padding: 1.6rem 2rem; border-radius: 8px; margin-bottom: 2rem;
+  padding: 1.6rem 2rem; border-radius: var(--radius-card); margin-bottom: 2rem;
 }
 .masthead h1 { margin: 0 0 0.3rem; font-size: var(--fs-h1); font-weight: 700; }
-.masthead .sub { font-size: var(--fs-meta); opacity: 0.85; margin: 0 0 0.15rem; }
+.masthead .sub { font-size: var(--fs-meta); opacity: 0.85; margin: 0 0 0.15rem; max-width: none; }
 .wordmark {
   position: absolute; right: 2rem; bottom: 1.2rem;
   font-size: var(--fs-dt); font-weight: 700; letter-spacing: 0.04em;
   color: var(--package-accent); background: #fff; opacity: 0.85;
-  padding: 0.1rem 0.5rem; border-radius: 999px; text-decoration: none;
+  padding: 0.1rem 0.5rem; border-radius: var(--radius-pill); text-decoration: none;
 }
 .wordmark:hover { opacity: 1; }
 .meta-grid {
@@ -99,10 +99,23 @@
   text-decoration: none; margin-left: auto;
 }
 .top-link:hover { color: var(--ocean); text-decoration: underline; }
-.note {
+.caption {
   color: var(--gray-5); font-size: var(--fs-note);
-  margin-top: -0.5rem; margin-bottom: 0.75rem;
+  margin-top: 0.75rem; margin-bottom: 0.75rem;
 }
+h2 + .caption { margin-top: -0.5rem; }
+.explainer {
+  font-size: var(--fs-note); color: var(--text);
+  background: var(--bg-sunken); border-left: 3px solid var(--muted);
+  padding: var(--sp-3); margin: -0.25rem 0 0.75rem; border-radius: var(--radius-btn);
+}
+.warn {
+  font-size: var(--fs-note); color: var(--text);
+  background: var(--warn-bg); border-left: 3px solid var(--warn);
+  padding: var(--sp-3); margin-bottom: 0.5rem; border-radius: var(--radius-btn);
+}
+.warn::before { content: "⚠ "; }
+.warn.error { border-left-color: var(--error); }
 .jump-nav {
   background: var(--seafoam); padding: 0.55rem 1rem;
   border-radius: 6px; margin-bottom: 1.5rem;
@@ -121,16 +134,33 @@
 .fig-col { display: flex; flex-direction: column; gap: 0.75rem; }
 figure { margin: 0; }
 figure img {
-  border: 1px solid var(--rule); border-radius: 4px;
+  border: 1px solid var(--rule); border-radius: var(--radius-btn);
   display: block; width: 100%; height: auto;
 }
 figcaption { font-size: var(--fs-cap); color: var(--gray-5); margin-top: 0.25rem; }
+table {
+  width: 100%; border-collapse: collapse;
+  font-size: var(--fs-note); margin: 0.6rem 0 1.2rem;
+}
+th {
+  background: var(--package-accent); color: #fff; text-align: left;
+  font-weight: 600; padding: 0.4rem 0.65rem;
+}
+th.num { text-align: right; }
+td {
+  padding: 0.35rem 0.65rem; border-bottom: 1px solid var(--rule);
+  vertical-align: top;
+}
+tr:nth-child(even) td { background: var(--bg-sunken); }
+td.num, .num { text-align: right; font-variant-numeric: tabular-nums; }
+td.mono { font-family: var(--font-mono); font-size: var(--fs-xs); }
 .slot-full         { width: 100%; }
 .slot-twothirds     { width: calc(66.67% - 0.33rem); }
 .slot-three-fifths  { width: calc(60% - 0.40rem); }
 .slot-half          { width: calc(50% - 0.50rem); }
 .slot-two-fifths    { width: calc(40% - 0.60rem); }
 .slot-third         { width: calc(33.33% - 0.67rem); }
+.slot-quarter       { width: calc(25% - 0.75rem); }
 .masthead-header {
   display: flex; justify-content: space-between; align-items: flex-start;
   margin-bottom: 0.3rem;
@@ -143,7 +173,7 @@
 .nav-btns { display: flex; gap: 0.5rem; }
 .btn-nav {
   background: var(--ocean); color: #fff; padding: 0.25rem 0.75rem;
-  border-radius: 999px; text-decoration: none; font-size: var(--fs-nav);
+  border-radius: var(--radius-pill); text-decoration: none; font-size: var(--fs-nav);
 }
 .btn-nav:hover { opacity: 0.85; }
 footer {
@@ -210,8 +240,10 @@
 /* Figures never exceed the content column; the oversampled PNG downscales
    crisply (spec §11 OVERSAMPLE). Pages may override (e.g. array uses 60%). */
 .fig { max-width:100%; height:auto; display:block; }
-td.num { text-align:right; font-variant-numeric:tabular-nums; }
-td.mono { font-family:var(--font-mono); font-size:var(--fs-xs); }
+/* A bare .fig (no slot class) is a full-width figure: fill the column. A
+   slot-* figure gets its width from the .slot-* rule instead — so this must NOT
+   apply to slotted figures (that was the width:100%-overrides-slot bug). */
+.fig:not([class*="slot-"]) { width:100%; }
 .none-note { color:var(--muted); font-style:italic; }
 .var-qc { color:var(--good); font-size:var(--fs-xs); }
 /* Figure-debug line under a plot (OCEANARRAY_REPORT_DEBUG=1): slot the
@@ -227,18 +259,10 @@
 }
 
   :root { --accent:#1e8449; --accent-link:#d5f5e3; }
-  .file-table { width:100%; border-collapse:collapse; font-size:0.81rem; margin-bottom:1.2rem; }
-  .file-table th { background:var(--seafoam); color:var(--text); text-align:left;
-                   padding:0.35rem 0.65rem; border-bottom:2px solid #cde; font-weight:700; }
-  .file-table td { padding:0.3rem 0.65rem; border-bottom:1px solid #eef; vertical-align:middle; }
-  .file-table tr:nth-child(even) td { background:#f4f9fc; }
+  /* Table style is canonical in emit_css now; only the file-table's cell
+     colour classes remain page-specific. */
   .file-table .ok { color:var(--good); font-weight:700; }
-  .file-table .miss { color:#bbb; }
-  table { width:100%; border-collapse:collapse; font-size:0.82rem; }
-  th { background:var(--ocean); color:#fff; padding:0.4rem 0.65rem;
-       text-align:left; font-weight:600; white-space:nowrap; }
-  td { padding:0.35rem 0.65rem; border-bottom:1px solid #ecf0f1; vertical-align:middle; }
-  tr:nth-child(even) td { background:var(--seafoam); }
+  .file-table .miss { color:var(--gray-3); }
   .badge { display:inline-block; padding:0.12em 0.45em; border-radius:3px;
            font-size:0.7rem; font-weight:700; white-space:nowrap; }
   .b-ok   { background:var(--good);   color:#fff; }
diff --git a/tests/fixtures/golden/dune2/instrument/dune2_1_2026_9920_report.html b/tests/fixtures/golden/dune2/instrument/dune2_1_2026_9920_report.html
index 0e0b70a..a4eaeca 100644
--- a/tests/fixtures/golden/dune2/instrument/dune2_1_2026_9920_report.html
+++ b/tests/fixtures/golden/dune2/instrument/dune2_1_2026_9920_report.html
@@ -67,15 +67,15 @@
 p, li { max-width: 78ch; }
 .masthead {
   background: var(--ocean); color: #fff; position: relative;
-  padding: 1.6rem 2rem; border-radius: 8px; margin-bottom: 2rem;
+  padding: 1.6rem 2rem; border-radius: var(--radius-card); margin-bottom: 2rem;
 }
 .masthead h1 { margin: 0 0 0.3rem; font-size: var(--fs-h1); font-weight: 700; }
-.masthead .sub { font-size: var(--fs-meta); opacity: 0.85; margin: 0 0 0.15rem; }
+.masthead .sub { font-size: var(--fs-meta); opacity: 0.85; margin: 0 0 0.15rem; max-width: none; }
 .wordmark {
   position: absolute; right: 2rem; bottom: 1.2rem;
   font-size: var(--fs-dt); font-weight: 700; letter-spacing: 0.04em;
   color: var(--package-accent); background: #fff; opacity: 0.85;
-  padding: 0.1rem 0.5rem; border-radius: 999px; text-decoration: none;
+  padding: 0.1rem 0.5rem; border-radius: var(--radius-pill); text-decoration: none;
 }
 .wordmark:hover { opacity: 1; }
 .meta-grid {
@@ -99,10 +99,23 @@
   text-decoration: none; margin-left: auto;
 }
 .top-link:hover { color: var(--ocean); text-decoration: underline; }
-.note {
+.caption {
   color: var(--gray-5); font-size: var(--fs-note);
-  margin-top: -0.5rem; margin-bottom: 0.75rem;
+  margin-top: 0.75rem; margin-bottom: 0.75rem;
 }
+h2 + .caption { margin-top: -0.5rem; }
+.explainer {
+  font-size: var(--fs-note); color: var(--text);
+  background: var(--bg-sunken); border-left: 3px solid var(--muted);
+  padding: var(--sp-3); margin: -0.25rem 0 0.75rem; border-radius: var(--radius-btn);
+}
+.warn {
+  font-size: var(--fs-note); color: var(--text);
+  background: var(--warn-bg); border-left: 3px solid var(--warn);
+  padding: var(--sp-3); margin-bottom: 0.5rem; border-radius: var(--radius-btn);
+}
+.warn::before { content: "⚠ "; }
+.warn.error { border-left-color: var(--error); }
 .jump-nav {
   background: var(--seafoam); padding: 0.55rem 1rem;
   border-radius: 6px; margin-bottom: 1.5rem;
@@ -121,16 +134,33 @@
 .fig-col { display: flex; flex-direction: column; gap: 0.75rem; }
 figure { margin: 0; }
 figure img {
-  border: 1px solid var(--rule); border-radius: 4px;
+  border: 1px solid var(--rule); border-radius: var(--radius-btn);
   display: block; width: 100%; height: auto;
 }
 figcaption { font-size: var(--fs-cap); color: var(--gray-5); margin-top: 0.25rem; }
+table {
+  width: 100%; border-collapse: collapse;
+  font-size: var(--fs-note); margin: 0.6rem 0 1.2rem;
+}
+th {
+  background: var(--package-accent); color: #fff; text-align: left;
+  font-weight: 600; padding: 0.4rem 0.65rem;
+}
+th.num { text-align: right; }
+td {
+  padding: 0.35rem 0.65rem; border-bottom: 1px solid var(--rule);
+  vertical-align: top;
+}
+tr:nth-child(even) td { background: var(--bg-sunken); }
+td.num, .num { text-align: right; font-variant-numeric: tabular-nums; }
+td.mono { font-family: var(--font-mono); font-size: var(--fs-xs); }
 .slot-full         { width: 100%; }
 .slot-twothirds     { width: calc(66.67% - 0.33rem); }
 .slot-three-fifths  { width: calc(60% - 0.40rem); }
 .slot-half          { width: calc(50% - 0.50rem); }
 .slot-two-fifths    { width: calc(40% - 0.60rem); }
 .slot-third         { width: calc(33.33% - 0.67rem); }
+.slot-quarter       { width: calc(25% - 0.75rem); }
 .masthead-header {
   display: flex; justify-content: space-between; align-items: flex-start;
   margin-bottom: 0.3rem;
@@ -143,7 +173,7 @@
 .nav-btns { display: flex; gap: 0.5rem; }
 .btn-nav {
   background: var(--ocean); color: #fff; padding: 0.25rem 0.75rem;
-  border-radius: 999px; text-decoration: none; font-size: var(--fs-nav);
+  border-radius: var(--radius-pill); text-decoration: none; font-size: var(--fs-nav);
 }
 .btn-nav:hover { opacity: 0.85; }
 footer {
@@ -210,8 +240,10 @@
 /* Figures never exceed the content column; the oversampled PNG downscales
    crisply (spec §11 OVERSAMPLE). Pages may override (e.g. array uses 60%). */
 .fig { max-width:100%; height:auto; display:block; }
-td.num { text-align:right; font-variant-numeric:tabular-nums; }
-td.mono { font-family:var(--font-mono); font-size:var(--fs-xs); }
+/* A bare .fig (no slot class) is a full-width figure: fill the column. A
+   slot-* figure gets its width from the .slot-* rule instead — so this must NOT
+   apply to slotted figures (that was the width:100%-overrides-slot bug). */
+.fig:not([class*="slot-"]) { width:100%; }
 .none-note { color:var(--muted); font-style:italic; }
 .var-qc { color:var(--good); font-size:var(--fs-xs); }
 /* Figure-debug line under a plot (OCEANARRAY_REPORT_DEBUG=1): slot the
@@ -227,18 +259,10 @@
 }
 
   :root { --accent:#1e8449; --accent-link:#d5f5e3; }
-  .file-table { width:100%; border-collapse:collapse; font-size:0.81rem; margin-bottom:1.2rem; }
-  .file-table th { background:var(--seafoam); color:var(--text); text-align:left;
-                   padding:0.35rem 0.65rem; border-bottom:2px solid #cde; font-weight:700; }
-  .file-table td { padding:0.3rem 0.65rem; border-bottom:1px solid #eef; vertical-align:middle; }
-  .file-table tr:nth-child(even) td { background:#f4f9fc; }
+  /* Table style is canonical in emit_css now; only the file-table's cell
+     colour classes remain page-specific. */
   .file-table .ok { color:var(--good); font-weight:700; }
-  .file-table .miss { color:#bbb; }
-  table { width:100%; border-collapse:collapse; font-size:0.82rem; }
-  th { background:var(--ocean); color:#fff; padding:0.4rem 0.65rem;
-       text-align:left; font-weight:600; white-space:nowrap; }
-  td { padding:0.35rem 0.65rem; border-bottom:1px solid #ecf0f1; vertical-align:middle; }
-  tr:nth-child(even) td { background:var(--seafoam); }
+  .file-table .miss { color:var(--gray-3); }
   .badge { display:inline-block; padding:0.12em 0.45em; border-radius:3px;
            font-size:0.7rem; font-weight:700; white-space:nowrap; }
   .b-ok   { background:var(--good);   color:#fff; }
@@ -519,7 +543,7 @@ <h2 id="hodograph">Hodograph</h2>
 <!-- ══ Speed distribution ══ -->
 
 <h2 id="speed">Current speed distribution</h2>
-<img class="fig" src="data:image/png;base64,<PNG>" style="max-width:300px;">
+<img class="fig slot-quarter" src="data:image/png;base64,<PNG>">
 
 
 <!-- ══ Analog channels ══ -->
diff --git a/tests/unit/test_report_golden.py b/tests/unit/test_report_golden.py
index 5783269..4f72cd2 100644
--- a/tests/unit/test_report_golden.py
+++ b/tests/unit/test_report_golden.py
@@ -165,8 +165,11 @@ def test_png_geometry_on_rendered_page(rendered_dir: pathlib.Path) -> None:
         for slot, b64 in _SLOT_IMG_RE.findall(html):
             width_px = Image.open(io.BytesIO(base64.b64decode(b64))).size[0]
             expected = round(tok.SLOTS[slot][1] * tok.FIG_DPI)
-            assert width_px == expected, (
-                f"{page}: slot-{slot} figure is {width_px}px, expected {expected}px "
+            # ±1 px: a half-integer inches*dpi (e.g. quarter = 2.25*150 = 337.5)
+            # is truncated by matplotlib (337) while round() gives 338.  The check
+            # exists to catch mis-slots, which are off by hundreds of px.
+            assert abs(width_px - expected) <= 1, (
+                f"{page}: slot-{slot} figure is {width_px}px, expected ~{expected}px "
                 f"(SLOTS[{slot!r}].inches={tok.SLOTS[slot][1]} * FIG_DPI={tok.FIG_DPI})"
             )
             checked += 1
diff --git a/tests/unit/test_report_tokens.py b/tests/unit/test_report_tokens.py
index a92c77b..d606ae4 100644
--- a/tests/unit/test_report_tokens.py
+++ b/tests/unit/test_report_tokens.py
@@ -65,6 +65,7 @@ def test_png_palette_colors():
         ("half", 675),
         ("two-fifths", 540),
         ("third", 450),
+        ("quarter", 338),
     ],
 )
 def test_png_width_table(slot, expected_px):
@@ -80,6 +81,7 @@ def test_width_aliases_match_slots():
     assert tok.W_HALF == tok.SLOTS["half"][1]
     assert tok.W_TWO_FIFTHS == tok.SLOTS["two-fifths"][1]
     assert tok.W_THIRD == tok.SLOTS["third"][1]
+    assert tok.W_QUARTER == tok.SLOTS["quarter"][1]
 
 
 def test_mplstyle_path_resolves():

From 2432c03452c0931394bc8f8b6c40e51f225eb96b Mon Sep 17 00:00:00 2001
From: Eleanor Frajka-Williams <eleanorfrajka@gmail.com>
Date: Sun, 16 Aug 2026 07:28:51 +0200
Subject: [PATCH 2/4] fix: correct signed-DMS coordinate parsing and
 recovery-table hemisphere

---
 oceanarray/reports/_recovery_table.py | 23 ++++++--------
 oceanarray/utilities.py               | 44 ++++++++++++++++++++++++---
 tests/unit/test_utilities.py          | 30 ++++++++++++++++++
 3 files changed, 79 insertions(+), 18 deletions(-)

diff --git a/oceanarray/reports/_recovery_table.py b/oceanarray/reports/_recovery_table.py
index 232a6db..9918e07 100644
--- a/oceanarray/reports/_recovery_table.py
+++ b/oceanarray/reports/_recovery_table.py
@@ -295,6 +295,7 @@ def generate_recovery_table(
     """
     from datetime import datetime, timezone
 
+    from ..utilities import format_latlon, parse_latlon_with_source
     from ._html_helpers import _duration_str
 
     proc_dir = Path(proc_dir)
@@ -318,19 +319,15 @@ def generate_recovery_table(
     deploy_dt = _parse_dt(cfg.get("deployment_time"))
     recover_dt = _parse_dt(cfg.get("recovery_time"))
 
-    # Latitude/longitude for the canonical meta fields, if available.
-    lat = (
-        cfg.get("seabed_latitude")
-        or cfg.get("deployment_latitude")
-        or cfg.get("latitude")
-    )
-    lon = (
-        cfg.get("seabed_longitude")
-        or cfg.get("deployment_longitude")
-        or cfg.get("longitude")
-    )
-    latitude = f"{lat} N" if lat else ""
-    longitude = f"{lon} W" if lon else ""
+    # Latitude/longitude for the canonical meta fields, if available.  Route through
+    # the shared parser (DMS-aware, pairs lat/lon from one key set, skips the (0, 0)
+    # placeholder) then format with the hemisphere derived from the sign — never a
+    # hardcoded suffix, which produced the malformed "-27.8 W" for signed inputs.
+    lat_v, lon_v, source = parse_latlon_with_source(cfg)
+    if source.startswith("unknown"):
+        latitude = longitude = ""
+    else:
+        latitude, longitude = format_latlon(lat_v, lon_v)
 
     rows, comments = _build_rows(proc_dir, mooring_name, cfg)
 
diff --git a/oceanarray/utilities.py b/oceanarray/utilities.py
index ed04766..6998704 100644
--- a/oceanarray/utilities.py
+++ b/oceanarray/utilities.py
@@ -684,7 +684,13 @@ def cast_output_dtypes(ds: xr.Dataset) -> xr.Dataset:
 
 
 def _dms_to_deg(s: str) -> float:
-    """Parse 'DD MM.mmm N/S/E/W' or a plain float string to decimal degrees."""
+    """Parse 'DD MM.mmm N/S/E/W', signed 'DD MM.mmm', or a plain float to decimal degrees.
+
+    The sign of a coordinate applies to the whole magnitude, not just the degrees
+    field: ``"-27 48.000"`` is -(27 + 48/60) = -27.8, not -27 + 48/60.  A leading
+    minus on the degrees field and a trailing ``S``/``W`` hemisphere are equivalent
+    ways to mark a negative value; either one negates the summed magnitude.
+    """
     s = s.strip()
     try:
         return float(s)
@@ -693,10 +699,38 @@ def _dms_to_deg(s: str) -> float:
     parts = s.upper().split()
     hemi = parts[-1] if parts[-1] in ("N", "S", "E", "W") else None
     nums = parts[:-1] if hemi else parts
-    val = sum(float(x) / 60.0**i for i, x in enumerate(nums))
-    if hemi in ("S", "W"):
-        val = -val
-    return val
+    negative = nums[0].startswith("-") or hemi in ("S", "W")
+    magnitude = sum(abs(float(x)) / 60.0**i for i, x in enumerate(nums))
+    return -magnitude if negative else magnitude
+
+
+def format_latlon(lat: float, lon: float, *, ndp: int = 4) -> tuple[str, str]:
+    """Return (lat, lon) as hemisphere-suffixed strings from signed decimal degrees.
+
+    The sign selects the hemisphere and the magnitude is shown unsigned, so a
+    formatted value can never carry both a minus sign and a hemisphere letter
+    (e.g. the malformed ``"-27.8 W"``).  Latitude uses ``N``/``S``, longitude
+    ``E``/``W``; a value of exactly 0 is rendered on the positive hemisphere.
+
+    Parameters
+    ----------
+    lat, lon : float
+        Latitude and longitude in signed decimal degrees.
+    ndp : int, optional
+        Number of decimal places for the magnitude (default 4 ≈ 11 m).
+
+    Returns
+    -------
+    tuple[str, str]
+        ``(lat_str, lon_str)``, e.g. ``("65.7319° N", "27.8000° W")``.
+
+    """
+    lat_hemi = "N" if lat >= 0 else "S"
+    lon_hemi = "E" if lon >= 0 else "W"
+    return (
+        f"{abs(lat):.{ndp}f}° {lat_hemi}",
+        f"{abs(lon):.{ndp}f}° {lon_hemi}",
+    )
 
 
 def parse_latlon(cfg: dict) -> tuple[float, float]:
diff --git a/tests/unit/test_utilities.py b/tests/unit/test_utilities.py
index 3d14a1d..fbd8237 100644
--- a/tests/unit/test_utilities.py
+++ b/tests/unit/test_utilities.py
@@ -337,3 +337,33 @@ def test_should_skip_regeneration_up_to_date(tmp_path):
     _touch(yaml, 100)
     _touch(out, 200)
     assert utilities.should_skip_regeneration(out, False, False, src, yaml) is True
+
+
+def test_dms_to_deg_plain_float():
+    """A plain decimal-degree string parses unchanged, sign preserved."""
+    assert utilities._dms_to_deg("-27.8") == pytest.approx(-27.8)
+    assert utilities._dms_to_deg("65.7319") == pytest.approx(65.7319)
+
+
+def test_dms_to_deg_hemisphere_suffix():
+    """A trailing S/W hemisphere negates the summed magnitude."""
+    assert utilities._dms_to_deg("29 25.878 W") == pytest.approx(-29.4313, abs=1e-4)
+    assert utilities._dms_to_deg("65 34.004 N") == pytest.approx(65.56673, abs=1e-4)
+
+
+def test_dms_to_deg_signed_degrees_negate_whole_value():
+    """A leading minus signs the whole magnitude, not just the degrees field.
+
+    Regression: ``"-27 48.000"`` is -(27 + 48/60) = -27.8, not -27 + 48/60 = -26.2.
+    """
+    assert utilities._dms_to_deg("-27 48.000") == pytest.approx(-27.8)
+
+
+def test_format_latlon_hemisphere_from_sign():
+    """format_latlon derives N/S and E/W from the sign; magnitude is unsigned."""
+    lat_s, lon_s = utilities.format_latlon(65.7319, -27.8)
+    assert lat_s == "65.7319° N"
+    assert lon_s == "27.8000° W"
+    lat_s, lon_s = utilities.format_latlon(-12.5, 42.0, ndp=1)
+    assert lat_s == "12.5° S"
+    assert lon_s == "42.0° E"

From 9fb33fd05c16c6ea7d7ca5e94db14a2b1f9724de Mon Sep 17 00:00:00 2001
From: Eleanor Frajka-Williams <eleanorfrajka@gmail.com>
Date: Sun, 16 Aug 2026 07:37:07 +0200
Subject: [PATCH 3/4] refactor: re-vendor report_tokens/_css for
 package-neutral emit_css
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ctdcast inverted the emit_css API so the vendored files name no package: the
PACKAGE_ACCENT dict is gone from report_tokens.py, and emit_css(package: str)
became emit_css(package_accent: str) — it takes the accent colour value rather
than looking one up. Re-vendor both files byte-identical to ctdcast.

Move oceanarray's accent choice into a new local reports/_report_css.py (the
package-specific wiring the vendored _css.py deliberately omits), and point
_env.py at its SHARED_CSS. The accent is var(--ocean) (= #1a3a5c), so the
rendered pages are pixel-identical; the golden re-baseline is the single
--package-accent line changing from the hex literal to var(--ocean).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 oceanarray/config/report_tokens.py            | 13 ++++------
 oceanarray/reports/_css.py                    | 24 ++++++++++---------
 oceanarray/reports/_env.py                    |  8 +++----
 oceanarray/reports/_report_css.py             | 23 ++++++++++++++++++
 .../dune2/dune2_1_2026_grid_report.html       |  2 +-
 .../golden/dune2/dune2_1_2026_report.html     |  2 +-
 .../dune2/dune2_1_2026_stack_report.html      |  2 +-
 .../instrument/dune2_1_2026_2941_report.html  |  2 +-
 .../instrument/dune2_1_2026_9920_report.html  |  2 +-
 9 files changed, 49 insertions(+), 29 deletions(-)
 create mode 100644 oceanarray/reports/_report_css.py

diff --git a/oceanarray/config/report_tokens.py b/oceanarray/config/report_tokens.py
index 51c23e9..4572888 100644
--- a/oceanarray/config/report_tokens.py
+++ b/oceanarray/config/report_tokens.py
@@ -207,15 +207,10 @@ def pen(name: str) -> float:
     "map": "#ee3377",
 }
 
-# Package accent (spec §12.2): confined to two additive places so it restyles no
-# existing pixel — a small masthead wordmark and the footer's border-top.  h2
-# underlines stay --seafoam and links stay --ocean.
-PACKAGE_ACCENT: dict[str, str] = {
-    "oceanarray": "#1a3a5c",
-    "ctdcast": "#0e6e6e",
-    "caldip": "#7a4b8a",  # reserved
-    "amocatlas": "#8a5a2b",  # reserved
-}
+# The package accent (spec §12.2) — a small masthead wordmark, the table header
+# and the footer's border-top — is NOT a value in this vendored file.  Each
+# package chooses it locally and passes it to ``emit_css(package_accent)`` (see
+# each repo's ``reports/_report_css.py``), so no per-package colour is encoded here.
 
 # Neutral gray scale — consolidates the ad-hoc grays that the per-page template
 # <style> blocks used (text shades, hairlines, sunken fills).  Emitted as
diff --git a/oceanarray/reports/_css.py b/oceanarray/reports/_css.py
index 236945b..333fa7c 100644
--- a/oceanarray/reports/_css.py
+++ b/oceanarray/reports/_css.py
@@ -1,15 +1,16 @@
 """Shared CSS for the report HTML pages, generated from the design tokens.
 
-``emit_css(package)`` builds the whole stylesheet string from
+``emit_css(package_accent)`` builds the whole stylesheet string from
 ``..config.report_tokens`` — colours, typography, spacing, radii and the slot
 table — so no value is restated here.  Its output is concatenated into each page
 template's ``<style>`` block (``{{ css | safe }}``).
 
 This module is written to be **vendored** across the packages that share the
-report design system: it names no package and reads shared values only through
-``..config.report_tokens``.  Which package's accent to render is an argument to
-``emit_css``, supplied by the (package-specific) caller — so the file itself
-carries no package-specific edit (Phase A; no cross-repo hash test yet, spec §9).
+report design system: it names no package and holds no per-package colour table,
+reading shared values only through ``..config.report_tokens``.  The accent
+colour to render is an argument to ``emit_css``, supplied by the
+(package-specific) caller — so the file itself carries no package-specific edit
+(Phase A; no cross-repo hash test yet, spec §9).
 """
 
 from __future__ import annotations
@@ -20,7 +21,6 @@
     FONT_MONO,
     FONT_SANS,
     GRAYS,
-    PACKAGE_ACCENT,
     RADII,
     ROLE_ACCENT,
     SEMANTIC,
@@ -69,7 +69,7 @@ def _emit_slots() -> str:
     return "\n".join(out)
 
 
-def emit_css(package: str) -> str:
+def emit_css(package_accent: str) -> str:
     """Return the full shared stylesheet as a string, generated from the tokens.
 
     Reproduces the established page look from the design tokens (spec §12–15 v2.0
@@ -82,11 +82,13 @@ def emit_css(package: str) -> str:
 
     Parameters
     ----------
-    package : str
-        Which package's accent to render (a key into ``PACKAGE_ACCENT``).  Passed
-        by the package-specific caller; the function itself names no package.
+    package_accent : str
+        The accent colour to render as ``--package-accent`` — any CSS colour
+        value, e.g. a hex literal or ``var(--ocean)``.  Chosen by the
+        package-specific caller; the function itself names no package and holds
+        no per-package colour table.
     """
-    root = _emit_root(PACKAGE_ACCENT[package])
+    root = _emit_root(package_accent)
     slots = _emit_slots()
     return f"""\
 {root}
diff --git a/oceanarray/reports/_env.py b/oceanarray/reports/_env.py
index 751b4b1..1aaf30f 100644
--- a/oceanarray/reports/_env.py
+++ b/oceanarray/reports/_env.py
@@ -19,7 +19,7 @@
 
 from . import _figdebug
 from . import _slots
-from ._css import emit_css
+from ._report_css import SHARED_CSS
 from .. import parameters as params
 
 #: Directory holding the report page templates.
@@ -42,9 +42,9 @@
 #: Generated stylesheet — the single source of truth for report CSS (tokens,
 #: type/spacing scale, slot classes, shared chrome).  base.html injects it via
 #: ``{{ css | safe }}``; page-specific rules live in a small local block that
-#: references these token variables (U0.1).  The vendored ``_css.py`` is called,
-#: never edited.
-_ENV.globals["css"] = emit_css(params.PACKAGE_NAME)
+#: references these token variables (U0.1).  The accent is applied in the local
+#: ``_report_css`` wiring; the vendored ``_css.py`` names no package.
+_ENV.globals["css"] = SHARED_CSS
 
 
 def render_template(name: str, /, **context: Any) -> str:
diff --git a/oceanarray/reports/_report_css.py b/oceanarray/reports/_report_css.py
new file mode 100644
index 0000000..30e10f8
--- /dev/null
+++ b/oceanarray/reports/_report_css.py
@@ -0,0 +1,23 @@
+"""oceanarray's concrete report stylesheet, from the package-neutral ``emit_css``.
+
+This is the package-specific wiring the vendored :mod:`oceanarray.reports._css`
+deliberately omits: the single place oceanarray's accent is applied to the shared
+generator.  Another package supplies its own accent the same way; the vendored
+``_css.py`` carries no package-specific edit, so re-vendoring it from the sister
+repo is a byte-identical copy.
+"""
+
+from __future__ import annotations
+
+from ._css import _JS_TOP_LINKS, emit_css
+
+#: oceanarray's package accent — chosen here, locally, not in the vendored tokens.
+#: Points at ``--ocean`` (structural navy ``#1a3a5c``) so the accent (wordmark,
+#: table header, footer rule) matches the heading colour; change this one line to
+#: rebrand.  Any CSS colour value works.
+PACKAGE_ACCENT: str = "var(--ocean)"
+
+#: The generated stylesheet, ready to concatenate into a page ``<style>`` block.
+SHARED_CSS: str = emit_css(PACKAGE_ACCENT)
+
+__all__ = ["SHARED_CSS", "_JS_TOP_LINKS"]
diff --git a/tests/fixtures/golden/dune2/dune2_1_2026_grid_report.html b/tests/fixtures/golden/dune2/dune2_1_2026_grid_report.html
index 055d3ab..9b6b5f4 100644
--- a/tests/fixtures/golden/dune2/dune2_1_2026_grid_report.html
+++ b/tests/fixtures/golden/dune2/dune2_1_2026_grid_report.html
@@ -31,7 +31,7 @@
   --role-aggregate-a: #8e44ad;
   --role-aggregate-b: #27ae60;
   --role-map: #ee3377;
-  --package-accent: #1a3a5c;
+  --package-accent: var(--ocean);
   --font-sans: system-ui, -apple-system, "Segoe UI", sans-serif;
   --font-mono: ui-monospace, "SF Mono", Menlo, Consolas, "DejaVu Sans Mono", monospace;
   --fs-root: 14px;
diff --git a/tests/fixtures/golden/dune2/dune2_1_2026_report.html b/tests/fixtures/golden/dune2/dune2_1_2026_report.html
index 519f8ef..cc5bd9e 100644
--- a/tests/fixtures/golden/dune2/dune2_1_2026_report.html
+++ b/tests/fixtures/golden/dune2/dune2_1_2026_report.html
@@ -31,7 +31,7 @@
   --role-aggregate-a: #8e44ad;
   --role-aggregate-b: #27ae60;
   --role-map: #ee3377;
-  --package-accent: #1a3a5c;
+  --package-accent: var(--ocean);
   --font-sans: system-ui, -apple-system, "Segoe UI", sans-serif;
   --font-mono: ui-monospace, "SF Mono", Menlo, Consolas, "DejaVu Sans Mono", monospace;
   --fs-root: 14px;
diff --git a/tests/fixtures/golden/dune2/dune2_1_2026_stack_report.html b/tests/fixtures/golden/dune2/dune2_1_2026_stack_report.html
index b21decd..b85eb55 100644
--- a/tests/fixtures/golden/dune2/dune2_1_2026_stack_report.html
+++ b/tests/fixtures/golden/dune2/dune2_1_2026_stack_report.html
@@ -31,7 +31,7 @@
   --role-aggregate-a: #8e44ad;
   --role-aggregate-b: #27ae60;
   --role-map: #ee3377;
-  --package-accent: #1a3a5c;
+  --package-accent: var(--ocean);
   --font-sans: system-ui, -apple-system, "Segoe UI", sans-serif;
   --font-mono: ui-monospace, "SF Mono", Menlo, Consolas, "DejaVu Sans Mono", monospace;
   --fs-root: 14px;
diff --git a/tests/fixtures/golden/dune2/instrument/dune2_1_2026_2941_report.html b/tests/fixtures/golden/dune2/instrument/dune2_1_2026_2941_report.html
index 248938e..5f1da07 100644
--- a/tests/fixtures/golden/dune2/instrument/dune2_1_2026_2941_report.html
+++ b/tests/fixtures/golden/dune2/instrument/dune2_1_2026_2941_report.html
@@ -31,7 +31,7 @@
   --role-aggregate-a: #8e44ad;
   --role-aggregate-b: #27ae60;
   --role-map: #ee3377;
-  --package-accent: #1a3a5c;
+  --package-accent: var(--ocean);
   --font-sans: system-ui, -apple-system, "Segoe UI", sans-serif;
   --font-mono: ui-monospace, "SF Mono", Menlo, Consolas, "DejaVu Sans Mono", monospace;
   --fs-root: 14px;
diff --git a/tests/fixtures/golden/dune2/instrument/dune2_1_2026_9920_report.html b/tests/fixtures/golden/dune2/instrument/dune2_1_2026_9920_report.html
index a4eaeca..a241094 100644
--- a/tests/fixtures/golden/dune2/instrument/dune2_1_2026_9920_report.html
+++ b/tests/fixtures/golden/dune2/instrument/dune2_1_2026_9920_report.html
@@ -31,7 +31,7 @@
   --role-aggregate-a: #8e44ad;
   --role-aggregate-b: #27ae60;
   --role-map: #ee3377;
-  --package-accent: #1a3a5c;
+  --package-accent: var(--ocean);
   --font-sans: system-ui, -apple-system, "Segoe UI", sans-serif;
   --font-mono: ui-monospace, "SF Mono", Menlo, Consolas, "DejaVu Sans Mono", monospace;
   --fs-root: 14px;

From 0d83ff8d323ac1d401d9319d77b16361f3cd2757 Mon Sep 17 00:00:00 2001
From: Eleanor Frajka-Williams <eleanorfrajka@gmail.com>
Date: Sun, 16 Aug 2026 07:56:01 +0200
Subject: [PATCH 4/4] test: cover parse_latlon_with_source fallback branches

---
 tests/unit/test_utilities.py | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/tests/unit/test_utilities.py b/tests/unit/test_utilities.py
index fbd8237..75d4786 100644
--- a/tests/unit/test_utilities.py
+++ b/tests/unit/test_utilities.py
@@ -367,3 +367,38 @@ def test_format_latlon_hemisphere_from_sign():
     lat_s, lon_s = utilities.format_latlon(-12.5, 42.0, ndp=1)
     assert lat_s == "12.5° S"
     assert lon_s == "42.0° E"
+
+
+def test_parse_latlon_with_source_unknown_when_absent():
+    """An empty config yields (0, 0) tagged as an unknown source."""
+    lat, lon, source = utilities.parse_latlon_with_source({})
+    assert (lat, lon) == (0.0, 0.0)
+    assert source.startswith("unknown")
+
+
+def test_parse_latlon_with_source_skips_zero_placeholder():
+    """A (0, 0) seabed placeholder is skipped for a later key with a real fix."""
+    cfg = {
+        "seabed_latitude": 0.0,
+        "seabed_longitude": 0.0,
+        "deployment_latitude": "-27 48.000",
+        "deployment_longitude": "10 30.000 E",
+    }
+    lat, lon, source = utilities.parse_latlon_with_source(cfg)
+    assert lat == pytest.approx(-27.8)
+    assert lon == pytest.approx(10.5)
+    assert source == "deployment_latitude/deployment_longitude"
+
+
+def test_parse_latlon_with_source_skips_unparseable_key():
+    """An unparseable coordinate string is skipped for the next valid key pair."""
+    cfg = {
+        "seabed_latitude": "not-a-coord",
+        "seabed_longitude": "also-bad",
+        "latitude": "65 34.004 N",
+        "longitude": "29 25.878 W",
+    }
+    lat, lon, source = utilities.parse_latlon_with_source(cfg)
+    assert lat == pytest.approx(65.56673, abs=1e-4)
+    assert lon == pytest.approx(-29.4313, abs=1e-4)
+    assert source == "latitude/longitude"