← All docs

Diagram authoring rules

Rules for writing pages in this repo. They exist so the guarantees of the diagram pipeline (zero client JS, theme-adaptive SVGs, audited contrast) survive convenience later. Deviations are build failures, not style opinions.

1. Prose first — diagrams illustrate

Every diagram must be introduced and summarized by ordinary HTML text around it: a paragraph before or after stating what it shows and why it matters.

Rationale:

• Crawlers weight real HTML prose far above SVG <text>; naive scrapers, read-later apps, and RSS readers strip SVG entirely.
• If a diagram ever fails to render, whatever was said only inside it disappears with it.
• Humans skim prose, then study diagrams — not the reverse.

Test: delete every diagram from the page mentally. If the point of the page doesn’t survive in words alone, write more words before adding graphics back.

2. Author colors are raw literals

Mermaid’s parsers reject var() outright (sequence box even rejects CSS tokens). Inside fences:

• Use raw hex literals (fill:#c92a2a). The tokenizer maps palette literals to CSS variables at build time.
• Pure black/white (#000, #fff, #ffffff) are reserved for authors: they survive verbatim so label-on-chip contrast survives theme flips. Never use them as backgrounds.
• Semi-transparent overlays are fine (rect rgb(88, 96, 120, 0.18)), but keep alpha low; the audit composites them over their backdrop.
• Gantt/sequence labels that overflow their band get checked at the label’s center point — size bars/durations so labels stay on them.

3. The audit is the gate

node scripts/check-contrast.mjs must pass at 4.5:1 for every diagram, in both themes, before deploy. It composites semi-transparent fills in paint order and checks foreignObject HTML labels too. A red audit means fix the colors, not the threshold.

4. Build hygiene

After touching src/plugins/, astro.config.mjs, or anything in the markdown dependency chain:

rm -rf dist node_modules/.astro node_modules/.vite && npm run build

Vite’s pre-bundle can serve stale plugin code that looks like a phantom bug. Also grep the build log for [ERROR]: a failed Mermaid parse emits an EMPTY page body and exits 0.

5. New diagram types

Each Mermaid diagram type ships its own color plumbing. When adding one: build once, run the leftover-literal scan plus the audit, then extend themeTokenMap / aliases until nothing mermaid-internal survives untokenized. Icon brand colors and deliberate C4 statics may stay raw — document them here when they do.