Editorial Diagrams

Create editorial-quality diagrams for blog posts as self-contained HTML files with inline SVG and CSS. Two brand skins — jjude.com and CTO Field Notes — each with their own palette, typography, and visual identity.

Based on cathrynlavery/diagram-design (MIT), adapted for Hermes.

When to Use

Use for blog post illustrations when a reader will learn more from a visual than from prose, a table, or bullet points. The 27 diagram types cover editorial, strategy, process, and conceptual illustrations — not cloud architecture (use architecture-diagram for that).

Don't use for:

Cloud/infra architecture → use architecture-diagram
Quick unicode diagrams → use excalidraw
One-shape "diagrams" → just write the sentence

Before drawing, ask: Would the reader learn more from this than from a well-written paragraph? If no, don't draw.

Brand Skins

Always ask which brand to use before generating. The two skins are:

Brand	Skin file	Palette feel
jjude.com	`references/style-guide-jjude.md`	Near-white, dark navy ink, blue accent, Gentium Book Basic
CTO Field Notes	`references/style-guide-ctofn.md`	White, charcoal ink, indigo accent, Spectral

Load the appropriate style guide before generating. Every token — paper, ink, muted, accent, rule, font stacks — comes from that file.

Philosophy

The highest-quality move is usually deletion.

Every node represents a distinct idea. Two nodes that always travel together are one node.
Every connection carries information. If the relationship is obvious from layout, remove the line.
Accent color on 1–2 focal elements per diagram. Using it on 5 nodes erases the signal.
Target density: 4/10. Above 9 nodes, it's probably two diagrams.

Diagram Types (Selection Guide)

If you're showing…	Use	Reference
Ranked hierarchy or conversion drop-off	Pyramid / funnel	`references/type-pyramid.md`
Two-axis positioning / prioritization	Quadrant	`references/type-quadrant.md`
Decision logic with branches	Flowchart	`references/type-flowchart.md`
Overlap between sets	Venn	`references/type-venn.md`
Events positioned in time	Timeline	`references/type-timeline.md`
Stacked abstraction levels	Layer stack	`references/type-layers.md`
Hierarchy through containment	Nested	`references/type-nested.md`
Parent → children relationships	Tree	`references/type-tree.md`
Cross-functional process with handoffs	Swimlane	`references/type-swimlane.md`
Multi-actor sequential process	Process	`references/type-process.md`
Reinforcing cycle / flywheel	Loop	`references/type-loop.md`
Components + connections	Architecture	`references/type-architecture.md`
Time-ordered messages between actors	Sequence	`references/type-sequence.md`
States + transitions	State machine	`references/type-state.md`
Entities + fields + relationships	ER / data model	`references/type-er.md`
Multiple entities across criteria (3-5 axes)	Radar / Spider	`references/type-radar.md`
Bar/line/scatter/Gantt charts	Chart types	`references/type-bar.md`, `type-line.md`, `type-scatter.md`, `type-gantt.md`
End-to-end data stack	High-Level	`references/type-high-level.md`
Data platform topology	Data platform	`references/type-data-flow.md`, `type-dp-integration.md`, `type-dp-security-matrix.md`
Multi-tier storage	Medallion	`references/type-medallion.md`
Legacy IT landscape	IT current-state	`references/type-it-state.md`

Always load the relevant references/type-*.md for the chosen type before drawing. It contains layout conventions, anti-patterns, and specific coordinates.

Quick Reference: Node Treatment

Type	Fill	Stroke
Focal (1–2 max)	`accent-tint`	`accent`
Backend / API / Step	white	`ink`
Store / State	`ink @ 0.05`	`muted`
External / Cloud	`ink @ 0.03`	`ink @ 0.30`
Input / User	`muted @ 0.10`	`soft`
Optional / Async	`ink @ 0.02`	`ink @ 0.20` dashed `4,3`
Security / Boundary	`accent @ 0.05`	`accent @ 0.50` dashed `4,4`

Core SVG Primitives

Background

Clean paper fill — no dot pattern by default:

<rect width="100%" height="100%" fill="#[paper]"/>

Dot pattern is opt-in for hero diagrams — see references/style-guide-*.md for paper color.

Arrow markers (define all three)

<marker id="arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
  <polygon points="0 0, 8 3, 0 6" fill="#[muted]"/>
</marker>
<marker id="arrow-accent" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
  <polygon points="0 0, 8 3, 0 6" fill="#[accent]"/>
</marker>
<marker id="arrow-link" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
  <polygon points="0 0, 8 3, 0 6" fill="#[link]"/>
</marker>

Draw arrows before boxes so z-order puts lines behind nodes.

Connector rules (non-negotiable)

1. Rounded right-angle elbows (r=8) only. Diagonal lines only when endpoints share an axis.

2. Arrow labels require 6–10px gap above connector + opaque mask rect.

3. No overlapping connectors. Crossings use the bridge/hop primitive.

4. Fan attach points — ≥12px apart on same box edge.

5. No connector behind non-endpoint box unless geometrically unavoidable (then dashed).

Node box pattern

<!-- Opaque paper mask -->
<rect x="X" y="Y" width="W" height="H" rx="6" fill="#[paper]"/>
<!-- Styled box -->
<rect x="X" y="Y" width="W" height="H" rx="6" fill="[FILL]" stroke="[STROKE]" stroke-width="1"/>
<!-- Node name (sans font from skin) -->
<text x="CX" y="CY+2" fill="#[ink]" font-size="12" font-weight="600"
      font-family="'[font-sans]', sans-serif" text-anchor="middle">Node Name</text>
<!-- Technical sublabel (mono font from skin) -->
<text x="CX" y="CY+18" fill="#[muted]" font-size="9"
      font-family="'[font-mono]', monospace" text-anchor="middle">sublabel</text>

Legend — horizontal bottom strip

Place after all nodes, with hairline separator. Expand viewBox height by ~60px.

Layout & Spacing

4px grid (hard rule)

All font sizes, padding, node dimensions, gaps, x/y coords divisible by 4. Exempt: stroke widths (0.8, 1, 1.2), opacities.

Category	Allowed values
Font sizes	8, 12, 16, 20, 24, 28, 32, 40
Node width/height	80, 96, 112, 120, 128, 140, 144, 160, 180, 200, 240, 320
Gap between nodes	20, 24, 32, 40, 48
Border radius	4, 6, 8

Complexity budget

Max nodes: 9
Max arrows: 12
Max accent elements: 2
If exceeded, split into overview + detail.

Page Layout

1. Header — eyebrow (mono, tracked), title (serif), optional subtitle

2. SVG diagram — clean, borderless, sits directly on page paper

3. Summary cards (full variant only) — 2-3 col grid, varied widths, no shadows

4. Footer — colophon in mono, muted, hairline top border

Output

Always produce a single self-contained .html file:

Embedded CSS (no external except Google Fonts)
Inline SVG (no external images)
No JavaScript required

Save to a user-specified path. Two output formats:

Format 1: Standalone Diagram

The diagram fills the entire canvas. Use for in-post illustrations.

wiki/produce/hermes/blogs/drafts/
├── [post-slug]/              ← diagrams tied to a specific draft
│   ├── draft.md
│   ├── diagram-[name].html   ← vector source, re-editable
│   └── diagram-[name].png    ← 2x raster for blog CDN
├── examples/                  ← reference/examples (browseable)
│   ├── jjude-content-pyramid.html + .png
│   ├── ctofn-tech-adoption.html + .png
│   ├── jjude-atomic-card.html      ← vertical 1200×1200, social media
│   ├── jjude-blog-card.html        ← horizontal 1200×628, featured image
│   └── ctofn-blog-card.html
└── standalone/                ← diagrams without an associated post
    └── [topic-slug].html + .png

Format 2: Blog Card (featured image)

A horizontal two-pane card for blog post featured images and social sharing.

Property	Value
Dimensions	1200×628 (landscape, OG image ratio)
Left pane	Diagram SVG (~54% width, 648px)
Right pane	Title + accent bar + excerpt (~46%)
Footer	Site brand + URL
Templates	`templates/blog-card-jjude.html`, `templates/blog-card-ctofn.html`

When to use: Every blog post gets a blog card as its featured image. Generate

the diagram for the left pane first (any of the 27 types), then embed it into the

blog card template. The right pane is filled from the post's title and excerpt.

Workflow for blog cards:

1. Load the blog card template for the brand: templates/blog-card-{jjude|ctofn}.html

2. Generate the diagram for the left pane (pick type → load references/type-*.md)

3. Replace the placeholder SVG in the template with the generated diagram

4. Fill in <h2> (post title) and <p class="excerpt"> (1–2 sentence takeaway)

5. Export PNG via Playwright

Example outputs:

assets/example-blog-card-jjude.png — jjude skin (near-white, navy, blue accent)
assets/example-blog-card-ctofn.png — CTO Field Notes skin (white, charcoal, indigo)

Format 3: Atomic Card (social media)

A vertical square card for social media posts and atomic essays.

Property	Value
Dimensions	1200×1200 (square)
Top zone	Diagram / illustration (~53%)
Bottom zone	Title + excerpt (~47%)
Templates	`templates/atomic-card-jjude.html`, `templates/atomic-card-ctofn.html`

Export

After generating the HTML, also export a 2x PNG via Playwright:

/opt/data/.venv/bin/python3 /opt/data/tools/export_png.py <diagram.html> <diagram.png> 2

Pre-Output Checklist

Type fit:

[ ] Right type for content? Would a table/paragraph do the same job?
[ ] Loaded the matching references/type-*.md?

Signal:

[ ] Accent used on ≤2 elements?
[ ] Within complexity budget?

Technical:

[ ] Arrows before boxes?
[ ] Rounded right-angle elbows (no diagonals)?
[ ] Arrow labels have 6–10px gap + mask rect?
[ ] No overlapping connectors?
[ ] Legend at bottom, not floating?
[ ] Every coord divisible by 4?

Typography (from skin):

[ ] Names in sans font, not mono?
[ ] Sublabels in mono font?
[ ] Title in serif font?

Workflow

1. Ask which brand skin to use (jjude.com or CTO Field Notes)

2. Load the matching references/style-guide-*.md

3. Choose the diagram type → load the matching references/type-*.md

4. Generate the HTML following all rules above

5. Run the pre-output checklist

6. Save to user-specified path

editorial-diagrams