Adding a diagram

A Mermaid fence renders on GitHub with GitHub’s theme and on the site as accessible inline SVG in the brand palette, at build time — no runtime JavaScript, indexed by search, readable by a screen reader.

The rules

• Start every diagram with accTitle: (a name) and accDescr: (one sentence). The gate warns on a missing title.
• Colours, if you set any, come from docs/brand/tokens.json; no %%{init} directives — the theme is central. Brand red never appears in a diagram.
• Labels are plain text (htmlLabels is off): use <br/> for a line break, nothing else.
• No scripture in a diagram, ever.
• Draw top to bottom (flowchart TB): the page’s column is narrow, and a wide left-to-right chart is scaled down until its text cannot be read, or scrolls sideways. Short labels; the detail goes in the prose.
• Give it an accDescr as well as an accTitle: the description is what a screen reader says.
• Keep it under about twelve nodes. Past that, write a poster: it steps, it zooms, and it carries a verified stamp.

Example

A pin bump reaches production

Checking it

make docs-check checks the palette and the title; make docs renders every fence and fails the build if one does not render (the check-mermaid step confirms none was left as a code block).