Skip to content

Infographics

Inline-SVG infographics: hand-authored vector visuals that live inside markdown. Diffable, re-derivable, light/dark-adaptive. Listed here are the live ones plus candidate pages waiting their turn.
🌱 seedling tended 2026-05-09 convention diagrams infographic compression 
flowchart LR
  page[a page worth illustrating] --> svg[hand-authored inline svg]
  svg --> css[shared infographics.css]
  css --> render[mkdocs render · light & dark]
  svg -.diff.-> review[git review]
Read next

Three live examples (PROVERBS, HOW-TO-SWARM, COMPRESSIONS) plus a candidate registry.

An infographic is a higher-resolution mermaid that you had to draw by hand.

What an infographic is here

An infographic in this repo is an inline <svg> block embedded in a markdown page — not a separate .png, .jpg, or generated image. Mermaid handles structural diagrams (flowcharts, state machines). When the visual needs metaphor, layout control, or icons that mermaid can't express, we drop down to hand-authored SVG.

Why SVG and not generated images:

Property PNG (model-generated) Inline SVG (hand-authored)
Diffable in git no — opaque blob yes — line-by-line
Light/dark mode one-shot, baked-in follows Material tokens
Editable in 30s regenerate from scratch change one number
Re-derivable from prose rarely usually
Reproducible seed-dependent byte-stable
Cost per fix one model call one keystroke

This is the same rate-distortion logic the rest of the repo runs on (see SWARM-RATE-DISTORTION.md): SVG is a lower-distortion codec for our editing workflow even though it costs more authoring effort up front.

Live examples

Page Concept Why this page
Proverbs A 4-station compression journey: lifetimes → 15 words → ear → fired action Best illustration of "intelligence is compression with a purpose" applied to humans
How to swarm Compounding-vs-resetting comparison + the orient → expect → act → diff → compress loop The methodology page deserves the methodology in one frame
Compressions One page → five lossy codecs, each with its ratio Meta-catalog page; the diagram is the catalog
Body as engine A six-gauge dial panel — breath, posture, tongue, gaze, voice, attention The dial-panel metaphor is the page; six dashboard gauges with what each modulates
Just godding One inline-SVG glyph per OmegaL atom — entities, relations, states, modifiers, plus a speculative-atoms block After Appleton 2024 / Just JavaScript: the canonical pictogram set so every diagram stops re-inventing local icons

How to author one

  1. Decide it earns its keep. If a 5-line mermaid would say the same thing, use mermaid. SVG is for visuals where shape, scale, or metaphor matter.
  2. Use the shared CSS. Import is automatic via mkdocs.yml. Apply classes from site_assets/assets/infographics.css instead of hardcoded fills/strokes — that's what makes dark mode work.
  3. Wrap in a <figure class="infographic">. Add a <figcaption> with a one-line summary. The figcaption is part of the prose contract: a screen reader user gets the punchline.
  4. Include <title> and <desc> inside the SVG. Title = ≤8 words. Desc = the same prose-version of the diagram a blind reader would need.
  5. Use viewBox, no fixed width/height. The CSS sets max-width 880px; the viewBox handles aspect ratio.
  6. Re-derivable from prose. If your prose around the infographic doesn't already convey the same conclusion, extend the prose — diagrams summarize, they don't replace.

Authoring template

<figure class="infographic">
  <svg viewBox="0 0 1100 480" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="ig-FOO-title ig-FOO-desc">
    <title id="ig-FOO-title">FOO — short headline</title>
    <desc id="ig-FOO-desc">Prose version of the diagram, one sentence.</desc>

    <!-- groups, paths, text using ig-* classes only -->
  </svg>
  <figcaption>One-line caption that stands alone as L0.</figcaption>
</figure>

How to test/fix

Concern Check
Valid XML xmllint --noout docs/PAGE.md won't work directly; copy the SVG into a .svg file or use a regex extract. The simplest test is mkdocs serve — Material logs SVG parse errors.
Light + dark Toggle the theme switcher in the rendered page. Anything hardcoded in fill="#000" will break — use class="ig-fill" instead.
Mobile Material's content column is ~720px on a phone; viewBox should keep labels legible at that width.
Prose parity Read the page with screen-reader CSS (display:none on .infographic svg). Does the prose still deliver the punchline? If no, the prose is incomplete.

Candidate registry

Pages where a hand-authored infographic would compress more than the existing prose+mermaid does. Sorted by expected payoff (how much visual metaphor unlocks understanding).

High payoff

Page What to depict Notes
SWARM-RATE-DISTORTION.md The R(D) curve with this repo's compression schemes plotted as points (proverb, glossary, mermaid L0/L1/L2, full prose) Page already references the curve verbally; visualizing it would be the headline image of the whole repo
MAP.md A "you are here" map of major doc clusters with reading-order arrows Already a map, but could be a richer terrain-style visual
HUMAN-GUIDE.md First-90-seconds onboarding flow: where to land, what to read, when to leave Onboarding pages are exactly where one image saves five minutes of skim
SCALING-TIMELINES.md Timeline of session counts vs. lessons accumulated, with phase markers Time-series pages benefit most
MATH-DEPENDENCY-TREES.md Dependency tree as a literal tree silhouette, theorems as leaves, axioms as roots The page name is the visual

Medium payoff

Page What to depict Notes
SWARM-LATTICE-THEORY.md Hasse diagram of the partial order with a few labeled elements Mermaid struggles with lattice geometry
SWARM-PLANT-LATTICE.md A literal stylized plant with labeled organs mapping to repo concepts Metaphor-driven page
PATTERNS.md A grid of pattern cards, each with its glyph + one-line trigger Patterns are visual by nature
RATING-AND-PRIORITY.md The 2×2 (impact × confidence?) with example items placed 2×2s are infographic-shaped already
EXPERT-POSITION-MATRIX.md The matrix as a labeled grid with diagonal/off-diagonal highlights Same
FUN-FACTS.md One small framed metaphor per fact, arranged in a gallery Repeats the pattern across many entries — a candidate for a generator, not one-offs
ECOSYSTEM-EXTRACTION.md Sankey-style extraction flows across the ecosystem Mermaid can't do Sankey well

Lower payoff (worth doing eventually)

Page What to depict
LEARN-AND-TEACH.md Two-direction teach/learn loop with a shared artifact in the middle
SWARM-CATEGORY-THEORY.md A small commutative-diagram glyph next to each functor introduced
EPISTEMIC-STATUS.md A status-bar legend (🌱 / 🌿 / 🌳) with example pages on a maturity timeline
GENESIS.md An origin-timeline visual: 2024 → present with key milestones
godding/swarm.md The swarm-as-organism metaphor visualized
godding/stigmergy.md Ants + pheromone trails + repo-state stigmergy mapping
godding/religion.md Proverbs scaled into a cooperation system: zoom-out from PROVERBS infographic

What to add to this list

When you tend a page and think "this would land harder with a visual", add a row above. The columns are intentionally minimal — the candidate just needs a name, a one-line "what to depict", and (optionally) a note. Don't pre-design; design happens when you sit down to author it.

Tooling pointers

  • The shared CSS lives at site_assets/assets/infographics.css. It's loaded site-wide via mkdocs.yml.
  • tools/build_site_src.sh copies site_assets/assets/* into site_src/assets/, so just edit in place.
  • For a new infographic, copy the template above, drop it into the target page near the L0 lead, and tend.

See also