# Mermaid In Artifacts

> Use mermaid for diagrams inside artifacts - the one visualization that renders natively with no library, no CSP problem, and no hand-rolled SVG. Covers what it is genuinely good for (process flows, decision trees, close calendars, system maps, org and approval chains), what it is bad for (anything quantitative), and the syntax and theming that survive both light and dark. Trigger on "diagram", "flowchart", "process map", "sequence diagram", "gantt", "org chart", "decision tree", "mermaid", "how do I draw a process".

- Skill: `lukehle/mermaid-in-artifacts` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lukehle/mermaid-in-artifacts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lukehle/mermaid-in-artifacts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Lukehle (https://skillmd.com/u/lukehle)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lukehle/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.

```markdown
```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.

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

### Close calendar

```mermaid
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.

```mermaid
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 `&quot;` 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:

```html
<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