Mermaid In Artifacts

Mermaid in artifacts

Artifacts render mermaid natively — no library, no CDN, no CSP problem. In an environment where every other visualization must be hand-built, that makes mermaid the cheapest thing on the menu, and it is routinely overlooked.

```mermaid
flowchart LR
  A[Extract] --> B{DQ gate}
  B -->|pass| C[Reconcile]
  B -->|block| D[Human review]

In an HTML artifact, use `<pre class="mermaid">…</pre>` instead of a fenced block.

---

## Use it for structure. Never for quantity.

The line is simple and it holds:

| Use mermaid | Use SVG (`svg-charting`) |
|---|---|
| Process and approval flows | Anything with a value axis |
| Decision trees | Bridges, bars, lines, areas |
| System and data-lineage maps | Cohort heatmaps |
| Close calendars and dependencies (gantt) | Anything where position encodes magnitude |
| Org and ownership chains | Anything a reader will measure |
| State machines | Distributions |

**Mermaid has no quantitative encoding.** Node size means nothing, edge length means nothing. The
moment a reader might compare two shapes to infer a number, you need a real chart. A "pie" in mermaid
is the worst of both — it looks quantitative and is unmeasurable.

---

## The five that earn their place in finance work

### Data lineage / pipeline map

The single most useful diagram for an automation owner. Answers "where does this number come from"
without reading code.

```mermaid
flowchart LR
  NS[(NetSuite)] -->|SuiteQL nightly| RAW[raw.gl_lines]
  SF[(Billing)]  -->|API| RAW2[raw.subscriptions]
  RAW  --> DQ{DQ gate}
  RAW2 --> DQ
  DQ -->|BLOCK| H[Human review]
  DQ -->|PASS| MART[finance.gl_summary]
  MART --> REC[AR reconciliation]
  MART --> BOARD[Board pack]

Approval / handoff chain

Makes the human-in-the-loop boundary explicit — who prepares, who approves, who executes.

flowchart LR
  P[Automation prepares JE] --> S[/STAGED/]
  S --> R{Controller reviews}
  R -->|approve| X[Human posts]
  R -->|reject| P

Close calendar

gantt
  title Close - July 2026
  dateFormat YYYY-MM-DD
  axisFormat %m/%d
  section Cutoff
    AP/AR cutoff        :done, c1, 2026-08-01, 1d
  section Subledger
    Bank rec            :done, s1, after c1, 1d
    AR to GL            :active, s2, after c1, 2d
  section Adjustments
    Accruals            :a1, after s2, 1d
  section Review
    Flux + statements   :r1, after a1, 2d

Decision tree

Encodes a policy so it can be followed identically each period.

flowchart TD
  V[Variance identified] --> M{Over materiality?}
  M -->|no| AGG[Aggregate into 'other']
  M -->|yes| D{Driver identified?}
  D -->|yes| C[Write commentary]
  D -->|no| GL[Pull GL detail, sort by magnitude]
  GL --> D

Sequence diagram

For anything with a time-ordered handoff between systems or people.

Syntax that avoids the common breakages

• Quote any label containing punctuation: A["Revenue (net)"]. An unquoted ( ) , : or # will break the parse, and the failure mode is a blank block rather than an error you notice.
• Escape or avoid " inside labels. Use " or rephrase.
• <br/> for line breaks inside a node — plain newlines will not work.
• Keep node ids short and alphanumeric (A, DQ, MART). Ids with spaces or hyphens are a frequent silent failure.
• Direction: LR for pipelines and lineage, TD for decisions and hierarchies. A wide TD diagram will overflow on a phone.

Theming for light and dark

The default mermaid theme does not always follow the viewer's theme, and a diagram that is unreadable in dark mode is unreadable for a large share of viewers. Pin it with an init directive:

%%{init: {'theme':'base', 'themeVariables': {
  'primaryColor':'#eef2f7','primaryTextColor':'#14161a','lineColor':'#5b6472',
  'primaryBorderColor':'#98a2b3','fontFamily':'ui-sans-serif, system-ui, sans-serif'
}}}%%
flowchart LR
  ...

Then verify in both themes. Per artifact-testing, "it rendered" is not "it is legible" — check the contrast of edge labels specifically, which are the first thing to disappear.

Sizing

Mermaid output can overflow its container on narrow screens. Wrap it:

<div style="overflow-x:auto">
  <pre class="mermaid"> … </pre>
</div>

Per artifact-architecture, wide content scrolls in its own container — the page body must never scroll horizontally.

When to stop using mermaid

Switch to hand-built SVG when you need:

• Precise positioning or alignment to a grid
• Interaction — hover, click-through, filtering
• Data-driven generation from a dataset rather than authored structure
• A value axis of any kind

A mermaid diagram is authored. Once it needs to be generated from data, it wants to be SVG.

Related skills

• svg-charting — everything quantitative
• artifact-architecture — why mermaid's native rendering is unusual and valuable here
• artifact-theming — the light/dark verification this depends on
• chart-selection — choosing between a diagram and a chart in the first place