ADR-035 — Diagram authoring pipeline: hand-drawn SVG, sources committed

Status · Accepted Date · 2026-05-07 Closes · RFC-011 (with ADR-034, ADR-036) TA anchor · §components / primary-route-pages Related · PRD-008, ADR-016 (build-time assets), ADR-019 (ajv schema validation)

Context

PRD-008 §design hints calls for ~30 SVG diagrams in /science — one per geometric concept (orbits, conic sections, transfer ellipses, porkchop axes, etc.). RFC-011 OQ-2 asked where the diagrams come from: hand-drawn Inkscape, Figma export, hand-coded SVG in JSON, programmatically generated via D3, or AI-generated. AI-generated was rejected for §principles attribution reasons.

Decision

Source format (RFC OQ-2 — Option A)

SVG diagrams live as committed source files at static/diagrams/science/[section].svg. The canonical authoring tool is open — Inkscape, Figma export, hand-coded SVG markup are all acceptable so long as the resulting .svg file is committed and dark-theme-compatible. The repo source is the authoring source; no separate .fig / .ai / .psd lives outside the tree.

Rationale: PRD-008 wants visual style consistency without locking us to one tool. Inkscape is the canonical reference (open source, dark-theme-friendly), but contributors using Figma or hand-coded SVG produce equivalent committed .svg artifacts. Programmatic generation (RFC-011 OQ-2 Option D) is left as a future option for diagrams that need to track data; manual SVG is V1.

Validation (fail-fast contract)

A new build script scripts/validate-diagrams.ts runs in CI alongside validate-data:

1. Loads every section JSON under static/data/science/.
2. For each section with a diagram field, asserts static/diagrams/science/[diagram-id].svg exists.
3. Fails the build if any reference is missing — same fail-closed model as image-provenance integrity (ADR-046).

Chained from scripts/validate-data.ts so a single npm run validate-data covers all data integrity.

Visual style

• Dark-theme native: transparent background, stroke palette #4ecdc4 (teal accent), #4466ff (blue accent), rgba(255,255,255,0.85) (foreground).
• 400×300 viewBox standard for desktop; SVG scales responsively at smaller widths.
• No inline <style>; styling via SVG attributes (stroke, fill, stroke-width) so the diagram renders identically in the encyclopedia and in any future export.

License

• Original geometric diagrams: project-owned under MIT (same as the rest of the codebase).
• Photos used in lieu of diagrams: public-domain or CC-BY only, attribution per ADR-046 / ADR-047 image-provenance pipeline.

Consequences

Positive: Cheapest path to V1; consistent visual language; per-section diagram changes are local file edits; CI catches dangling references at build. Future migration to programmatic generation (D3, custom build step) is per-diagram opt-in.

Negative: Hand-authored diagrams scale poorly past ~30. If /science doubles in size we'll revisit programmatic generation. Quality of complex pedagogical illustrations (rocket cutaways, EDL sequences) depends on the contributor; V1 ships schematic-quality SVGs that future contributors can replace with Inkscape passes.

Implementation notes

• Diagram directory: static/diagrams/science/.
• Validator: scripts/validate-diagrams.ts, chained into npm run validate-data.
• Quality flag: section JSON's optional diagram_quality: "schematic" | "polished" field documents which diagrams expect a future polish pass.
• Photos: still allowed (CC-BY / NASA / Wikimedia); section schema accepts either diagram or photo, never both for the primary visual.