Mermaid Visual Standard

Purpose

Mermaid is a semantic visual language, not a box-sizing system.

The primary goal is to make meaning visible while preserving natural Mermaid geometry.

The canonical model is:

SHAPE
→ structural entity type

COLOR
→ semantic / epistemic status

EMOJI
→ concept identity

EDGE
→ relation type / epistemic force

SUBGRAPH
→ context / perspective / boundary

The diagram should remain understandable even when color or emoji is ignored.

Core principles

Semantics first.
Natural geometry.
Small, stable visual vocabulary.
Consistent meanings across diagrams.
No presentation hacks in Mermaid source.
Renderer owns geometry; publication layer owns global presentation scale.

Do not redesign a graph merely to make all diagrams occupy the same canvas size.

A diagram may naturally be wider, taller, or denser when its meaning requires it.

Scope and applicability

These rules apply to all Mermaid diagram types, not only flowcharts. Apply the semantic intent through the notation and visual channels that the selected type actually provides. The vocabulary is shared; its syntax is not forced onto every diagram.

Semantic fidelity is mandatory in every diagram: every native construct must retain the meaning of the domain being modeled. Epistemic integrity is mandatory whenever a diagram represents knowledge, sources, observations, claims, evidence, hypotheses, uncertainty, contradiction, validation, or accepted understanding. Do not impose epistemic categories on diagrams that model only chronology, structure, interaction, or quantitative data.

For each diagram, use the applicable channels:

Structure: use native shapes, symbols, node kinds, stereotypes, or task/event types to distinguish meaningful structural roles. Do not invent shape meanings where the diagram type has no shape vocabulary.
Color: use the canonical semantic palette when styling is supported and color helps distinguish semantic or epistemic status. Do not color every item just to apply the palette; preserve data-series colors and type-specific color meanings when those are the diagram’s primary semantics.
Identity: add one functional emoji to each visible concept label whenever a recommended symbol clearly identifies that concept and the target Mermaid syntax supports it. This applies across diagram types, not only to flowchart nodes or diagram roots. Keep repeated concepts on the same emoji. Do not add emoji to relation syntax, exact data values, IDs, or identifiers; use a native display label or alias when available to keep those exact strings unchanged. Omit emoji only for the affected label when syntax does not support it, no suitable symbol exists, exact text must remain untouched, or the emoji would materially impair comprehension. Formal or dense diagram types are not by themselves a reason to omit emoji. If an entire diagram has no eligible labels, record the concrete reason in surrounding documentation or review notes.
Relations: use native arrows, links, dependencies, associations, containment, ordering, or other connectors to express the relation actually modeled. Use solid/dotted epistemic force only where the notation supports it and the relation really is accepted vs uncertain; never reinterpret chronology, cardinality, dependency, or message order as evidential strength.
Boundaries: use the type’s native grouping mechanism only for a real context, actor, layer, phase, namespace, or responsibility boundary.

If a visual channel is unavailable, ambiguous, or misleading for a diagram type, leave it unused and preserve meaning in labels, structure, or a legend. Do not convert a diagram to a flowchart solely to gain access to shapes or styling.

Guidance by diagram family

These are semantic mappings, not mandatory syntax templates. Mermaid capabilities vary by diagram type and version; use only syntax supported by the target renderer.

Flowcharts: map node shapes to structural roles, edge styles to relation semantics, and subgraphs to real boundaries.
Sequence diagrams: treat participants as actors or systems, messages as interactions, and activate/deactivate as execution state. Use participant boxes for actual actor or context groupings. Do not use arrow style to imply evidence strength unless that is genuinely what the message represents.
Class diagrams: use classes, interfaces, stereotypes, associations, and multiplicities for their structural meanings. Put functional emoji in visible class/interface labels or stereotypes when supported, but preserve class IDs, member names, and signatures exactly. Apply semantic color to classes only when status is relevant; do not confuse class kind or relationship type with epistemic status.
ER diagrams: preserve entity, attribute, relationship, and cardinality semantics. Keep provenance, evidence, claims, and understanding distinct in names or annotations when relevant; do not substitute colors for cardinality.
State diagrams: distinguish states from transitions and use initial/final, choice, fork, or join pseudostates only when the modeled control flow requires them. Add functional emoji to eligible visible state labels (for example, validation or accepted completion), without changing state IDs or transition syntax. A choice or validation state may use uncertainty styling when it represents a genuinely unresolved gate.
Mind maps: treat hierarchy as decomposition or association as intended by the content, not automatically as causality or evidence. Style major branches by semantic category only when the categories are meaningful and consistent.
Gantt, timeline, and journey diagrams: preserve task, milestone, date, sequence, actor, stage, and score meanings. Distinguish status with color only when status is present in the source information; do not imply epistemic status through schedule or journey position.
Git graphs: commits, branches, merges, and tags represent repository history. Keep branch/merge structure truthful; apply semantic styling only where it adds a separate, clear status dimension.
Requirement diagrams: retain requirement types, IDs, verification status, and trace relationships. A requirement is not evidence of its own satisfaction.
Architecture, C4, block, packet, and similar structural diagrams: use native components, actors, boundaries, layers, and connectors for the entities and relationships they represent. Group only real system or responsibility boundaries.
Data-focused diagrams such as pie, XY chart, quadrant, Sankey, and similar plots: prioritize accurate values, units, labels, axes, categories, and legends. Add a functional emoji to eligible category or series display labels when supported, but never alter numeric values, units, IDs, or exact source labels. Use color for data categories or series as appropriate; do not force node shapes or epistemic relations into a notation that does not support them.

The list is illustrative, not exhaustive. Apply the same reasoning to newer or specialized Mermaid diagram types.

Composition guidance

Prefer:

flowchart TD for conceptual and epistemic diagrams;
one obvious reading direction;
concise labels;
meaningful convergence;
0–2 lateral supporting branches per level when possible;
semantic pastel colors;
consistent functional emoji coverage for eligible concept labels;
subgraphs only for real context, layer, boundary, perspective, or actor grouping.

LR is allowed when the semantics are genuinely horizontal or when it materially improves readability.

The former diagram from “12. From DSL to Mermaid” remains a useful example of clear semantic composition, but it is not a mandatory size, topology, node-count, or footprint target.

Semantic + Epistemic Visual Vocabulary

Shape = structural type

Use a small shape vocabulary.

Structural role	Preferred Mermaid form	Typical concepts
orientation / state / synthesis / result	rounded `([text])`	Intent, Observation, Understanding, Result
process / assertion / transformation	rectangle `[text]`	Action, Claim, Evidence, Projection
unresolved branch / gate / tension	diamond `{text}`	Unknown, Decision, Contradiction, Validation Gate
source / store / corpus	cylinder `[(text)]`	Source, Reference, Dataset, Knowledge Store
context / layer / perspective / actor boundary	`subgraph`	Context, Perspective, Runtime Layer, Responsibility

Do not assign one unique shape to every concept.

Reuse the same shape whenever the structural category is the same.

Color = semantic or epistemic status

Canonical semantic palette:

classDef context fill:#D9EAF7,stroke:#7AA6C2,color:#3E342C,stroke-width:2px;
classDef observation fill:#DDF3E8,stroke:#78AA91,color:#3E342C,stroke-width:2px;
classDef claim fill:#FFF1BF,stroke:#C8A84E,color:#3E342C,stroke-width:2px;
classDef evidence fill:#E8DDF5,stroke:#A68BC4,color:#3E342C,stroke-width:2px;
classDef hypothesis fill:#F8DFC4,stroke:#C9986D,color:#3E342C,stroke-width:2px;
classDef uncertainty fill:#F6D6DD,stroke:#BF7C89,color:#3E342C,stroke-width:2px;
classDef contradiction fill:#F4CFC8,stroke:#B96B5D,color:#3E342C,stroke-width:2px;
classDef understanding fill:#DCEFD6,stroke:#86A878,color:#3E342C,stroke-width:2px;
classDef projection fill:#ECEBE8,stroke:#9C9992,color:#3E342C,stroke-width:2px;
classDef orchestration fill:#DDE3F4,stroke:#8998C8,color:#3E342C,stroke-width:2px;

Recommended meanings:

context — source, framing, provenance, environment;
observation — observed or reported state;
claim — assertion requiring support;
evidence — support, measurement, corroboration;
hypothesis — provisional explanation or mechanism;
uncertainty — unresolved, incomplete, unknown;
contradiction — conflict or incompatible support;
understanding — synthesized accepted understanding;
projection — explicit representation or action derived from understanding;
orchestration — coordination, capability, system-level control.

Color must communicate role, not decoration.

Emoji = concept identity

Recommended vocabulary:

📚 Source / Reference / Context
👁 Observation
🧭 Intent / Orientation
🔎 Inquiry / Evidence
🧪 Validation / Experiment / Replication
🔗 Relation
🧩 Hypothesis / Mechanism / Structure
⚠️ Claim / Contradiction / Warning when context disambiguates
❓ Unknown / unresolved question
🧠 Understanding
🌀 HOLOFLUX / semantic movement when explicitly relevant
⚙️ COSMOS / orchestration / capability when explicitly relevant
📄 Projection / Artifact / Explicit Form
▶️ Action
✅ Accepted Result / Checkpoint

Use at most one functional emoji per visible concept label unless there is a strong semantic reason to do otherwise. Apply one wherever a recommended symbol clearly fits and the diagram syntax permits it; do not limit emoji to roots or major nodes. Keep the same concept on the same emoji throughout a diagram and document.

Never change an identifier, exact label, command, requirement ID, or data value to insert emoji. Prefer a syntax-supported display alias or label. If none exists, or if no symbol clearly fits, omit emoji only from that item. Do not use diagram density or formality as blanket exemptions; omit an emoji only when it would materially reduce comprehension. Reviewers should be able to identify eligible labels and the concrete reason for any diagram-wide omission.

Edge = relation semantics

Primary accepted structural, operational, or semantic relation:

-->

Hypothesis, uncertainty, weak association, unresolved relation, or relation under inquiry:

-.->

In Mermaid source, use:

-. label .->

Use short edge labels such as:

supports
derived from
observes
qualifies
unresolved
inquiry
projects
revises

Use feedback loops for revision, re-evaluation, inquiry, learning, or recurrence.

Do not visually imply evidential strength unless the content actually establishes it.

Subgraph = context / perspective / boundary

Use subgraph when a visible boundary clarifies:

context;
perspective;
runtime layer;
environment;
responsibility;
actor boundary;
phase.

Do not use subgraphs as decorative containers.

Epistemic integrity

Whenever any part of a diagram models knowledge, preserve these distinctions in the relevant nodes, labels, and relationships:

Citation ≠ Source
Source ≠ Evidence
Evidence ≠ Claim
Claim ≠ Understanding
Operational success ≠ Epistemic acceptance
Retrieval ≠ Semantic extraction
Generated citation span ≠ Source passage

Additional rules:

a source is not evidence merely because it contains a supporting statement;
evidence supports or challenges claims but is not itself the claim;
a claim does not become understanding because it is repeated;
an unknown is not an error;
a contradiction is not automatically falsification;
successful tool execution is not epistemic validation;
retrieval success does not imply semantic correctness.

Canonical example

This example is a semantic reference, not a required topology or footprint.

Refactor mode

When applying this skill to an existing diagram:

read the surrounding content;
identify the Mermaid diagram type and what it is meant to communicate;
identify entity types, relation types, native type-specific semantics, and whether the diagram represents epistemic concepts;
preserve domain semantics, not accidental topology or styling;
when epistemic concepts are present, keep sources, observations, claims, evidence, uncertainty, contradiction, and accepted understanding distinct;
map structural roles to native shapes or symbols where supported;
apply semantic colors only where useful and supported;
add a functional emoji to every eligible visible concept label, preserving exact identifiers and values through native display labels where supported; record any diagram-wide omission with its concrete syntax or comprehension reason;
encode accepted vs uncertain relations only through a supported, truthful relation convention;
use native grouping only for a real context or boundary;
preserve domain-specific meanings such as ordering, cardinality, dates, and data values;
render and inspect the result with the target Mermaid renderer when available.

Rebuild only when semantic clarity, reading order, or visual coherence requires it.

Do not reconstruct merely to match another diagram’s size.

Sizing and rendering

Source-level rule

Do not encode final presentation size into Mermaid source.

Avoid:

minNodeWidth used as a presentation hack;
wrappingWidth used only to normalize appearance;
invisible padding;
artificial spaces;
artificial <br/> only to equalize boxes;
per-diagram pixel width rules;
adding or removing semantic nodes merely to fill space.

Natural geometry

Let Mermaid determine the natural geometry of:

node shapes;
label width;
edge routing;
branch spacing;
graph bounds.

Different shapes are expected to have different natural dimensions.

That difference is semantic and intentional.

Deterministic rendering

When a static renderer is available, prefer:

@mermaid-js/mermaid-cli@12.0.0

Canonical deterministic pipeline:

Mermaid source
→ mmdc 12.0.0
→ static SVG
→ preserve viewBox and internal geometry
→ optional single global display scale
→ responsive presentation

The publishing layer may reduce or enlarge the whole SVG uniformly.

It must not independently resize nodes or normalize individual diagrams with different fixed CSS widths.

Responsive presentation may use:

max-width: 100%;
height: auto;

For environments such as GitHub or VS Code that render Mermaid directly, keep the same semantic source and allow the host renderer to present it naturally.

Layout defaults

For flowcharts, prefer:

flowchart TD
nodeSpacing: 36
rankSpacing: 44
curve: basis
fontSize: 13px

These are defaults, not immutable laws.

Increase spacing before reducing typography.

Split a diagram when the semantic load becomes excessive.

Do not add nodes merely to reach a target node count.

Decision diamonds

Use a diamond only when the node genuinely represents:

a decision;
a gate;
an unresolved question;
a contradiction/tension point;
validation with branching implications.

Do not use diamonds simply to make the diagram visually varied.

Shape consistency

Variation is encouraged when it carries meaning.

The rule is:

same structural meaning
→ same shape

different structural meaning
→ shape may differ

Do not vary shapes for decoration.

Document-wide consistency

Across one document or product family, ensure:

the same concepts use the same semantic colors;
the same structural roles use the same shapes;
emojis retain their meanings;
solid and dotted edges retain their meanings;
labels stay concise;
subgraphs represent the same kinds of boundaries;
terminology remains consistent.

Consistency means semantic consistency, not identical diagram dimensions.

Avoid

arbitrary shape variation;
decorative colors;
decorative emojis;
hub-and-spoke layouts with many equal branches unless the domain actually is hub-and-spoke;
automatic LR for every graph;
unnecessary subgraphs;
long prose inside nodes;
forced equal pixel heights;
wrapper growth to compensate for graph design;
rebuilding a graph only to imitate a golden footprint;
hiding uncertainty behind solid arrows;
visually collapsing Source, Evidence, Claim, and Understanding.

Authoring syntax

Use the Mermaid fence required by the current environment.

For ordinary Markdown / GitHub / VS Code, use the fenced code language mermaid.

For Jekyll repositories that explicitly require mermaid!, use the fenced code language mermaid!.

A Mermaid fence must contain a complete, valid diagram (for example, beginning with flowchart TD), not a placeholder such as .... When documenting fence syntax, write it inline rather than nesting literal Mermaid fences in Markdown pages processed by the static renderer.

Fence conversion is a publishing concern. Do not modify diagram semantics during that conversion.

Quality gate

Before accepting a diagram, verify:

Is the semantic purpose clear?
Are the rules adapted to this diagram type instead of imposed literally?
Does every native construct preserve the modeled domain’s meaning?
If epistemic concepts are present, are their roles and relationships kept distinct without overstating support or acceptance?
Is operational success kept separate from epistemic validation or acceptance?
Does every eligible visible concept label have a consistent functional emoji?
Are any emoji omissions limited to specific syntax, exact-text, missing-symbol, or comprehension constraints, with a concrete reason for diagram-wide omission?
Does each shape encode a structural role?
Does each color encode semantic or epistemic status?
Are emojis functional rather than decorative?
Do edge styles reflect actual relation semantics?
Are native meanings such as chronology, cardinality, dependencies, scores, or data values preserved?
Are Source, Observation, Claim, Evidence, Unknown, Contradiction, and Understanding kept distinct?
Are labels concise?
Are subgraphs meaningful?
Did the author avoid sizing hacks?
Is natural geometry preserved?
If static rendering is used, is the SVG viewBox preserved?
If scaling is needed, is it applied uniformly to the whole SVG?
Does the diagram remain understandable without relying solely on color?

Guiding principles

Preserve semantic meaning, not existing topology.

Shape expresses what kind of thing it is.

Color expresses what epistemic or semantic status it has.

Emoji identifies the concept.

Edge style expresses the nature of the relation.

Let the renderer preserve natural geometry.

Consistency is semantic consistency, not identical footprint.