authoring-mermaid-diagrams

Choose the type based on the question the diagram answers: flowcharts for process steps and branches, sequence diagrams for who calls whom, state diagrams for states and transitions, ER diagrams for entities and cardinality. The Skill provides a question-to-type matrix covering over 30 types.

GitHub pins an older Mermaid version than mermaid.live, so beta-only types like radar-beta or swimlane-beta and newer syntax may not parse. Use stable-tier types or the -beta spelling that older embedded renderers accept, and avoid click interactions which GitHub strips.

Run node scripts/check-mermaid.mjs on your Markdown files to catch unrecognised keywords, deprecated %%{init}%% directives, missing accessibility headers, and unbalanced quotes. For a true parse, render with mmdc from @mermaid-js/mermaid-cli, which the script invokes automatically when on PATH.

Yes, but hardcoded colors break when hosts switch themes. Never set fill without color or vice versa, and prefer theme: base with themeVariables so derived colors stay consistent. Only the base theme accepts themeVariables; setting them under other themes is silently ignored.

Every diagram should include accTitle (single-line) and accDescr (single-line or multi-line brace form) in the body. These emit title and desc elements plus aria attributes in the SVG, making the diagram readable to screen readers and to anyone reading the raw Markdown.

Skip a diagram when the content is a short sequential list of facts, since diagrams exist to show relationships like order, containment, branching, and flow. For rich charts with real axes and many series, a dedicated chart library beats Mermaid's built-in chart types.