#119 Phase 3b: Diagram adoption across concepts and insights

[Anonymous]

Originally created by: TheoV823

Context

Phase 3 (#118) shipped four canonical HTML+CSS diagram primitives in site/assets/css/diagrams.css and embedded each on its canonical concept page:

• .mneme-diagram--propagation → /concepts/governance-propagation/
• .mneme-diagram--checkpoints → /concepts/governance-before-generation/
• .mneme-diagram--chain → /concepts/enforcement-provenance/
• .mneme-diagram--cascade → /concepts/architectural-drift/

Phase 3 deliberately stopped at the four canonical homes. The visual language now exists; this issue tracks adoption across the rest of the site so it does not remain a four-page one-off.

The contributor-facing visual-language reference lives at docs/contributing/diagram-conventions.md.

Scope

1. Inventory existing SVGs across concept and insight pages. Walk site/concepts/** and site/insights/** and produce a list of every <svg viewBox= instance with its page, line, and a one-line description of what the SVG depicts. Approximately 30 SVGs total; 2 were replaced and 1 was kept-alongside in Phase 3, the rest are untouched.

2. Classify each SVG. For each, assign one of:

3. Keep — the SVG remains the right depiction; no primitive applies.
4. Replace with existing primitive — one of the four Phase 3 primitives covers the argument; swap the SVG for the primitive (subject to the Phase 3 replacement rule: only when the CSS primitive is clearly smaller or theme-token cleaner, more accessible, and at least semantically equivalent).
5. New primitive needed — the argument is reusable across pages but is not covered by the existing four; design a fifth (or sixth) primitive in a separate PR before adopting.

6. Remove — the SVG is stale or duplicates content already covered elsewhere on the same page.

7. Prioritize concept pages first, then insights. Concept pages are the conceptual authority surface; getting them visually consistent matters more than insights.

8. Add a content checklist rule to whichever contributor doc the team uses for new pages (likely an update to docs/contributing/diagram-conventions.md or wherever the page-creation checklist lives): every new concept page or major insight that includes a diagram must use either (a) an existing CSS primitive from diagrams.css, (b) a justified new primitive added in a separate PR, or (c) an explicit no-diagram rationale recorded in the PR description. This prevents the inline-SVG count from growing again.

Execution suggestion

• A single ticket can produce the inventory + classification table; the adoption itself can happen as several smaller PRs (one per page or per primitive family) so review stays narrow.
• Apply the same per-PR discipline Phase 3 used: replace-vs-keep table in the PR description, per-page diff sizes, mneme check baseline comparison, headless visual smoke at 360 / 640 / 1024.

Out of scope

• Changing the four Phase 3 primitives themselves. If a new primitive is needed, that is a separate design+PR cycle (filed against a different issue).
• Atomization of primitives into shared __node / __arrow / __caption rules. Tracked separately; should only happen after enough adoption has revealed real reuse patterns.
• Full shared-stylesheet refactor (base.css + shared.css). Stays deferred per existing memory.

References

• PR [#118] — Phase 3 canonical diagram primitives.
• Visual language spec: docs/contributing/diagram-conventions.md.
• Design + implementation plan (private): mneme-growth-ops/docs/plans/2026-05-21-canonical-diagram-primitives-design.md and 2026-05-21-canonical-diagram-primitives-implementation.md.
• Phase 3 PR replace/keep/add table (use as the template for Phase 3b PRs).