[REFACTOR] vendor shared report design tokens, encoder, and CSS

[eleanorfrajka]

Summary

Introduces the shared design-token foundation for the report subsystem: a single source of truth for figure sizing, colours, typography, and the report matplotlib style, plus the figure encoder and CSS generator that read from it. These files are vendored from the sister ctdcast package and kept byte-identical so the two projects' reports stay visually consistent. This change is additive — nothing in the live report path imports the new modules yet, so report output is unchanged. The wiring into report generation lands in follow-up work; this establishes the foundation and its tests first.

Vendored shared foundation (provenance)

Four files are copied byte-identical from ../ctdcast (both projects are MIT-licensed and maintained under ocean-uhh). A cross-repo consistency check is planned but not added yet; for now the copies are kept in sync by hand.

• oceanarray/config/report_tokens.py — geometry (W_FULL, FIG_DPI, the SLOTS table, USABLE_PX, derived OVERSAMPLE), colours (COLORS, ROLE_ACCENT, PACKAGE_ACCENT, a neutral GRAYS ramp), the page type scale (TYPE), spacing (SPACE/RADII), and the RAISE_ON_PLOT_ERROR policy flag.
• oceanarray/config/report.mplstyle — the report matplotlib profile. It has no savefig.dpi; the encoder passes dpi=FIG_DPI explicitly instead.
• oceanarray/report/_encode.py — render_b64 / _fig_to_base64: the single choke point where a figure becomes base64 PNG bytes (constrained-layout guard, full-canvas save, 256-colour palette quantization). Package-neutral — imports only ..config.report_tokens.
• oceanarray/report/_css.py — emit_css(package) generates the shared stylesheet from the tokens. package is a required argument, so the file carries no project-specific value; oceanarray passes "oceanarray" when the CSS is wired in.

The vendored files name no project (only the PACKAGE_ACCENT data keys "oceanarray"/"ctdcast" remain), so both projects vendor identical copies.

Enforcement tests

tests/unit/test_report_tokens.py pins the sizing invariants without rendering a page: the slot contract (each slot's width in inches equals W_FULL × fraction), the geometry math (USABLE_PX, the derived OVERSAMPLE), the exact saved-PNG width for each slot (round(inches × FIG_DPI) = 1350/900/810/675/540/450 px), the width aliases, and an encoder smoke test confirming a full-canvas save is exactly W_FULL × FIG_DPI = 1350 px wide. Five further enforcement checks that require a rendered page or later wiring (PNG geometry on a real page, stray-typography, self-containment, the optional=True ratio, caption classification) are committed as skipped stubs so the full test surface is documented up front.

PR #70 review nits

Zero-output-change cleanups on code introduced by PR #70: a shared _PANEL_HEIGHT = 2.0 constant replacing duplicated literals in diagnostic.py and _plots.py; draw_windows's panels parameter moved to signature order in the docstring and passed by keyword at its call site; the _pdf.py max-height comment corrected to describe the cap as a backstop now that multipanel figures are paginated; and removal of a dead _dt_one variable.

CONTRIBUTING and commit convention

Updates CONTRIBUTING.md to add a Licensing of contributions section (inbound = outbound; contributors must flag code adapted from elsewhere and name its source and licence — directly relevant to the vendoring above), a stronger testing standard (assert a justifiable value, not merely result is not None), a credit and authorship section, an explicit never silently substitute a default provenance rule, and a one logical change per pull request guideline. Switches the project's commit-message and PR-title convention from bracket tags to conventional-commit prefixes (feat:, fix:, refactor:, docs:, test:, ci:, chore:), matching recent history and the sister project.

Packaging and lint

pyproject.toml adds config/*.mplstyle to package-data so report.mplstyle ships in a built wheel (otherwise a non-editable install would fail to find it at runtime once the encoder is wired in), plus per-file ruff exemptions for the two vendored modules whose docstring/try-except style differs from oceanarray's — kept as configuration so the copies stay byte-identical rather than being edited.

Testing

Full suite: 756 passed, 9 skipped. ruff check clean. All four vendored files verified byte-identical to ../ctdcast; emit_css("oceanarray") verified to emit oceanarray's navy accent (#1a3a5c), not ctdcast's teal.

Breaking changes

None. Purely additive: no public API removed or changed; the new modules are unused by the live report path; the PR #70 nits are documentation, dead-variable, and shared-constant edits.