Authoring diagrams and scenes
The handbook supports diagrams and animated scenes directly in Markdown. Authors can stay in prose-first .md and .mdx files without importing React components for every visual.
Elucim scenes
Use a fenced elucim block for diagrams and animated scenes. This should be the default choice for handbook visuals because the result reads better, supports motion, and keeps the diagram source close to the prose.
YAML is the default authoring format because it keeps scenes readable inside chapters. Use scene.type: player, a timeline, and a default state machine when the scene should animate.
If the scene YAML is invalid, the page renders a visible error card with the parser message and the original scene source so the author can fix it in place.
Mermaid diagrams
Use a fenced mermaid block only when a simple static chart is enough or when the source needs to stay portable outside the handbook. Prefer Elucim for conceptual diagrams, loops, flows, and anything that benefits from animation.