Skip to main content

Diagrams Standard

Summary​

This standard defines requirements for accessible, maintainable, secure, and validated diagrams.

Audience​

  • Documentation authors
  • Solution architects

Reference Content​

Use a diagram only when it communicates a relationship, sequence, state, boundary, or hierarchy more clearly than prose.

Mermaid​

Prefer Mermaid for maintainable diagrams supported by the portal. Every Mermaid block must:

  • Use syntax supported by the configured Docusaurus Mermaid integration.
  • Have a short introduction and a text explanation of the important conclusion.
  • Use meaningful generic labels and a logical reading order.
  • Remain understandable in light and dark themes.
  • Avoid relying on color alone.
  • Be validated in the production build and reviewed in the rendered page.

Other diagram assets​

Use version-controlled SVG or optimized raster formats only when Mermaid is unsuitable. Store the editable source when licensing and tooling permit. Provide concise alternative text and, for complex diagrams, an equivalent text description.

Never include secrets, confidential identifiers, unapproved infrastructure details, or production data in a diagram.

See Also​

Keywords​

  • Mermaid
  • Diagrams
  • Visual accessibility

Revision Information​

  • Last reviewed: 2026-07-14
  • Owner: documentation-team
  • Status: Approved