Content Mermaid

Produces Mermaid diagrams for technical processes and structures. This is the fast, syntax-driven counterpart to content-diagrams: same visual-clarity standards, but built on a language that already guarantees correct geometry, so the effort goes into picking the right diagram type and a readable, consistent color system instead of verifying coordinates.

Relationship to content-diagrams

Both skills share the same standards — legible text, a real color system instead of decoration, clarity over density — but content-diagrams computes its own SVG geometry by hand while this skill hands geometry entirely to Mermaid's layout engine; pick between them based on where the diagram will actually be viewed (native Mermaid surface vs. a platform that only shows static images), not habit, and if genuinely unsure, ask — Mermaid source doesn't screenshot cleanly into a polished standalone graphic without real rework.

Why there's no verification loop here

content-diagrams spends most of its effort on geometry: an SVG line, box, or label is just numbers Claude computed, and computed numbers can be wrong — hence render, screenshot, crop, and check.

Mermaid removes that failure mode entirely. Node width, text wrapping, arrow paths, and collision avoidance between elements are the renderer's job, not Claude's — the renderer will not place a label on top of a box or route a line through a shape. Re-deriving that verification loop here (screenshotting the rendered diagram, cropping, checking overlaps) would just burn tokens and latency confirming something the tool already guarantees.

What can still go wrong is entirely different, and entirely textual:

• Broken syntax (unclosed brackets, a reserved word used as a node ID, mismatched arrow types)
• An edge referencing a node ID that's never defined
• Poor color contrast (a fill and text color that don't actually read against each other)
• The wrong diagram type for the content's actual structure

So verification here means: read the syntax once for correctness, check every classDef pairs a fill with a genuinely contrasting text color, and confirm the diagram type matches what's being modeled. No image rendering required.

Diagram type selection

Pick the type from what the content structurally is — this is the Mermaid equivalent of content-diagrams' motif selection:

Don't default to flowchart for everything — a request like "diagram how our services call each other" is a sequenceDiagram even though it's tempting to draw it as boxes and arrows; a request like "show the states a ticket goes through" is stateDiagram-v2, not a flowchart with diamonds standing in for states.

Color and readability system

This is the one place manual verification still matters, because Mermaid will happily render illegible color choices without complaint.

The rule: every classDef must pair a fill with a text color that's been deliberately chosen to contrast with it — never leave color unset and hope the theme's default works. Mermaid's own default palette (soft green/pink/blue with black text) is fine precisely because fill and text were chosen together; the moment you override fill to something more saturated or dark, you must also set color explicitly, or you'll reproduce a common defect: readable-looking boxes with text that's actually low-contrast against them.

Two palette recipes, pick one and use it consistently across every class in one diagram (don't mix):

1. Dark fill / white text (the default — proven, high contrast, reads well in both light and dark chat themes):

   classDef category1 fill:#1e3a5f,stroke:#0d1f33,stroke-width:2px,color:#ffffff

2. Light tint fill / dark text / saturated stroke (use when a diagram needs to sit visually next to a content-diagrams SVG that follows its light-tint convention):

   classDef category1 fill:#e1f0ff,stroke:#1e3a5f,stroke-width:2px,color:#1a1a1a

Borrowing content-diagrams' rule directly: one hue per category, applied everywhere that category shows up — the same color in fill/stroke on every node of that role, not a one-off. Assign hues by role, e.g.:

• Blue → inputs / data / backlog items
• Green → process / active work steps
• Amber or brown → decision points / gates
• Purple → outputs / releases / terminal states
• Red → feedback loops / failure paths / retrospective

Lock the canvas so it doesn't depend on the host's light/dark mode. Put an init directive as the very first line of the diagram:

%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'Trebuchet MS, Verdana, Arial, sans-serif', 'fontSize': '16px', 'primaryColor': '#1e3a5f', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0d1f33', 'lineColor': '#666666', 'background': '#ffffff' } } }%%

theme: 'base' plus explicit themeVariables means the diagram looks the same regardless of which Mermaid theme the host environment defaults to — don't rely on the default theme name (default, dark, forest, etc.) alone, since that leaves the actual colors up to whatever the renderer decides.

Font size: 16px minimum for any diagram with more than a handful of nodes; 14px only if the diagram is simple enough that legibility isn't in question. If a diagram needs to shrink below 14px to fit its labels, that's the same "clarity over density" signal from content-diagrams — split the diagram or cut content, don't shrink text further.

Styling reach differs by diagram type: flowchart, stateDiagram-v2, and classDiagram all support per-node classDef/class assignment directly, so use the category-color system above node by node. sequenceDiagram, erDiagram, and gantt have much more limited per-element styling — for those, put the effort into the themeVariables in the init block (actorBkg, actorTextColor, noteBkgColor, etc. for sequence diagrams) rather than expecting node-level classes to work the same way.

Arrow grammar

Unlike hand-coded SVG, Mermaid renders arrow labels cleanly with automatic placement — -->|label| text doesn't risk landing on top of a shape the way a manually-positioned SVG label would. So, unlike content-diagrams' "keep text off arrows, decode via legend" default, labeling arrows directly is fine and often clearer here. Still keep labels to short fragments ("approved," "retry," "on failure") rather than phrases — a label is a tag, not a sentence.

Reserve line style for the same broad distinction content-diagrams uses:

• Solid arrow (-->) → primary/normal flow
• Dashed arrow (-.->) → feedback, an optional path, or an external/indirect interaction
• Thick arrow (==>) → an emphasized or critical path, used sparingly

Keep labels short; use subgraphs to group

Node text should be a short phrase, not a sentence — Mermaid will wrap or overflow awkwardly on paragraph-length labels just like any other tool. If a node needs multiple lines, insert them explicitly with <br/> inside the label rather than trusting auto-wrap to break in a sensible place.

Use subgraph to cluster related steps (e.g., everything inside one sprint, one deployment stage, one service boundary) — it's the Mermaid equivalent of a grouping box, and can be styled with its own style SubgraphName fill:...,stroke:... line. Don't nest subgraphs more than one level deep; it gets hard to read fast.

Workflow

1. Identify the underlying structure and pick the diagram type from the table above before writing any syntax.
2. Assign category colors to the roles present (inputs, process steps, decisions, outputs, feedback) — sketch this out in a sentence or two before writing classDefs, same as content-diagrams' "sketch the motif reasoning" step, so the choice is auditable if the user wants to adjust one piece.
3. Write the diagram, starting with the %%{init: ...}%% directive, then structure, then classDef/class assignments (or themeVariables for types that don't support per-node classes).
4. Self-check the syntax — every node ID used in an edge is defined somewhere; every classDef has both fill and color set; brackets/quotes are balanced; no paragraph-length label. No rendering, no screenshotting.
5. Save as a .mermaid file via create_file so it renders inline as an artifact, using a descriptive slug: /mnt/user-data/outputs/<slug>.mermaid. Present with present_files.
6. If the user needs the diagram as a portable static image (for embedding somewhere that won't render Mermaid, or for archival), say so plainly: this environment doesn't reliably run headless Mermaid-to-image export (it depends on a Chromium download that the sandboxed network usually can't reach). Point to mermaid.live for a manual export, or switch to content-diagrams if the real requirement is a standalone graphic.

What not to do

• Don't leave a classDef's color unset after overriding fill — that's the exact contrast bug this skill exists to avoid.
• Don't mix the dark-fill and light-fill palette recipes within one diagram.
• Don't default every request to flowchart — pick the type that matches the actual structure (sequence, state, ER, etc.).
• Don't reintroduce content-diagrams' render/crop/verify loop here — it's solving a problem Mermaid's layout engine doesn't have.
• Don't put paragraph-length text in a node label; wrap with <br/> or cut the content.
• Don't nest subgraphs more than one level.
• Don't promise a clean PNG/SVG export from this sandbox without caveating that headless Mermaid rendering may not work here.