Visual Standards designed
The portal should use visuals where they reduce cognitive load. A diagram is part of the documentation contract: it needs source ownership, review, and a clear update path.
Use Diagram Backlog to decide which diagrams to build next and which audience each visual serves.
Decision Rule
| Need | Preferred format | Why |
|---|---|---|
| Sequence, ownership, state, dependency, release flow | Mermaid | Reviewable text, easy diffs, lives beside the page. |
| Product screenshot or UI evidence | Image artifact | Shows the real interface; use only when source and freshness are clear. |
| Rich concept illustration, branded overview, visual metaphor | Maintained image | Use when Mermaid cannot express the idea cleanly. |
| API/event/entity lookup | Generated reference or table | Keeps contract details tied to source artifacts. |
Mermaid First
Use Mermaid for diagrams that must evolve with architecture or process docs. Keep labels short, avoid visual cleverness, and link the page back to canonical source docs.
Docusaurus supports Mermaid through @docusaurus/theme-mermaid and
markdown.mermaid: true. The official diagram docs show Mermaid code blocks,
the dynamic Mermaid component, theming, and optional layout configuration. The
Docusaurus test page also exercises many Mermaid diagram types, including
sequence, flowchart, class, state, entity relationship, user journey, pie,
gitgraph, mindmap, quadrant, and Mermaid architecture diagrams.
When Mermaid Is Not Enough
Use an image when the visual needs:
- real UI state,
- screenshots of evidence,
- product or brand composition,
- visual hierarchy that would be unreadable in Mermaid,
- externally shareable diagrams that need manual design polish.
This is also how Docusaurus handles its own architecture overview: the architecture guide embeds a maintained PNG diagram instead of Mermaid when the layout needs precise grouping, callouts, and visual hierarchy.
Store maintained portal images under packages/docs/static/img/portal/. Name
files by page and purpose, for example:
packages/docs/static/img/portal/security-readiness-release-rings.png
packages/docs/static/img/portal/app-sdk-developer-path.png
Every image-backed page should still include source_docs that explain the
claim the image is making. Screenshots should name the source environment or
artifact in nearby text.
Static Diagram Pattern
For curated static diagrams:
- Keep the rendered image under
packages/docs/static/img/portal/. - Keep the editable source beside it when possible, for example
.drawio,.fig,.excalidraw, or.svg. - Name the source doc or architecture decision that the image explains.
- Add alt text that is useful without the image.
- Re-render the image when the source docs change.
Use PNG for screenshots and broad compatibility. Use SVG when the diagram is hand-authored, reviewable, and does not leak hidden metadata.
Example:
The image is the presentation layer; the canonical explanation remains in
source_docs.
External inspiration:
Review Rules
- Architecture diagrams require architecture review.
- Security posture diagrams require security review.
- Product screenshots or journey visuals require product/frontend review.
- Public, customer, or partner visuals require visibility review before publication.
- If the visual explains a contract, update the canonical source before the portal page.
Diagram Roadmap
The visual roadmap lives in Diagram Backlog. It separates P0 onboarding diagrams, P1 deep-dive diagrams, and P2 supporting diagrams so visuals can land with the same discipline as source-doc consolidation.