Mermaid Diagram Skill

Field	Value
Type	Skill Resource
Source	~/.copilot/skills/technical-writing/references/mermaid.md
Description	Not specified

Source Content

Diagram rules (formerly the standalone mermaid skill), now owned by technical-writing.

Mermaid Diagram Skill

Hard Rules

• Run the pre-generation checklist before writing any Mermaid block.
• Run validation after drafting and before final output.
• Prefer flowchart over legacy graph.
• Prefer stateDiagram-v2 over stateDiagram.
• Keep every diagram focused on one reader question; if you can’t state its purpose in one sentence, it is two diagrams.
• Always group flowchart nodes with subgraph; never leave a flowchart flat. Pick the grouping that teaches the most — and when the flow crosses people and systems, group by what people do vs. automation first.
• In flowcharts, nodes are states or actions, never actors. Imply the actor through the group (e.g. a What people do subgraph) or put them on an edge label (-->|reviewer approves|); do not add Developer(("Developer")) actor nodes.
• Subgraph labels name the boundary (What people do, Production), not the contents (Step 1).
• Budget 5–7 nodes; collapse adjacent steps or split into two diagrams beyond that. Groups don’t count toward the budget.
• Default to flowchart TD; use LR only when direction itself carries meaning (a pipeline, a timeline).
• Color and shape teach, never decorate: color marks the people/automation boundary, the punchline node, or success vs. failure; shapes are [ ] action, { } decision, (( )) start/end only.
• Always put an icon on every node that can render one (house style). Give every actor, role, system, and outcome a consistent inline icon — an icon plus short text reads far faster than text alone, so a node without one (in a type that supports them) is a miss. Use inline monotone FontAwesome — the FREE set — (fas:fa-* solid / fab:fa-* brands, at the start of the label) — Node["fas:fa-user Label"]. FontAwesome Free is the single icon standard for diagrams on every surface (design system and docs). Pick only icons that exist in the free set (solid + brands) so they actually render. Never a Pro-only glyph, never emoji (they vary by OS, render as tofu, and read as AI-generated), and never a second pack. Inline fas:/fab: tokens render in every diagram type whose labels pass through Mermaid v11’s unified text renderer. Verified at 11.16.0: flowchart, stateDiagram-v2, classDiagram (quoted-label form class X["fas:fa-… Name"]), mindmap (inline fas:fa-… Label — NOT the ::icon() form, which needs a registered icon pack and renders nothing from the stylesheet alone), block-beta, and erDiagram labels. They do not render in sequenceDiagram, timeline, gitGraph, or C4* — there the token leaks as the literal text fas:fa-…, a visible defect; they are silently dropped in journey, gantt, sankey, and xychart; and they break the parser in quadrantChart and requirementDiagram (the : collides with the type’s own syntax). Keep every one of those types plain and monotone (never emoji); architecture-beta ships its own built-in shape icons (server, database, cloud, disk). If a diagram would be clearer with icons on every node but its type can’t render them, model it as a flowchart. Colour is monotone-first: default nodes, borders, and icons to monochrome and add colour only when it teaches — the people/automation boundary, the punchline node, or success vs. failure — or when explicitly asked. See icons-and-surfaces.md and the icon vocabulary in diagram-principles.md.
• Multi-layer system/topology diagrams are the exception to the shape and actor restrictions above. When a diagram shows a whole pipeline or architecture (GitOps flow, CI/CD, infra topology) rather than a single people/automation boundary, every distinct layer or role must get its own shape + muted color pair from the palette in gitops-patterns.md. That covers actors, durable stores, control planes, runtimes, environment stages, and manual gates. Leaving such a diagram in one shape and one color is a defect, not a stylistic choice. Pipeline start/end actors (who triggers it, who receives the result) may be drawn as (( )) circles even in a flowchart for this diagram type — the one case where a flowchart gets actor nodes.
• Edge labels say how, not what (on merge, never then); node labels are noun phrases (Open PR, not The developer opens a PR).
• Sequence diagrams are the exception — there, actors are participants: declare people with actor before participant, labeled plainly (Developer, Reviewer, Release Manager, Incident Lead, Platform Owner).
• Keep diagrams balanced: no long horizontal trains, no endless vertical ladders.
• Use short labels; put explanation in surrounding prose.
• Use safe node IDs only: [A-Za-z0-9_]. Do not use reserved words such as end, graph, flowchart, style, class, subgraph, or direction.
• Quote labels with spaces, punctuation, or special characters: A["Label: example"].
• Do not use inline HTML except the few renderer-tested node-label cases documented in references.
• For beautiful-mermaid flowcharts, do not use classDef or class; use direct style Node ... lines. This renderer can expose a stray visible class node.
• Lint changed diagrams with scripts/mermaid_lint.py before final handoff.

Quick Workflow

1. Identify the reader question — state the diagram’s purpose in one sentence.
2. Pick the diagram type.
3. Decide the grouping boundary (people vs. automation first) and wrap nodes in subgraphs.
4. Sketch the smallest useful diagram — 5 to 7 nodes, TD unless direction means something.
5. Check syntax rules for the chosen type.
6. Validate with the linter or renderer.
7. Fix and re-run until clean.

When To Read References

• For the design layer — grouping, people-vs-automation, node budget, color/shape discipline, the worked groupings — read diagram-principles.md. Read this before drafting any flowchart.
• For the icon standard — inline FontAwesome (fas:/fab:) on every surface (design system and docs alike), why inline beats icon-nodes, how to load FontAwesome per surface, the monotone-first colour rule, and the concept→token map, read icons-and-surfaces.md.
• For choosing a chart type, read chart-selection.md.
• For a digital-service-team catalog — sixteen diagram types grouped by lifecycle phase (understand users, design, connect, deliver, measure), each with when-to-use / when-not guidance, a worked example, and a rendered gallery to agree the house look — read service-team-diagrams.md.
• For GitOps people-vs-automation grouping patterns, color palettes, subgraph zone patterns, and the system node palette, read gitops-patterns.md.
• For per-diagram syntax examples, subgraph syntax, and sequence diagram constructs, read syntax-reference.md.
• For current Mermaid v11 flowchart syntax — the @{ shape: ... } typed shapes, icon nodes (@{ shape: icon }), FontAwesome/iconify packs, and newer arrows — read flowchart-shapes-and-icons.md.
• For beautiful-mermaid renderer constraints (supported types, styling rules, text alignment limits, blank lines, initial fit), read beautiful-mermaid-constraints.md.
• For lint commands, common errors, and the final self-rubric, read validation.md.

Pre-Generation Checklist

• Type selected and supported by the target renderer.
• Reader question is clear; purpose states in one sentence.
• Nodes grouped by the most meaningful boundary (people vs. automation when both are present) — not a flat chain.
• In an icon-capable type (flowchart, stateDiagram-v2, classDiagram, mindmap, block-beta, erDiagram), every actor, role, system, and outcome carries a consistent inline FontAwesome icon (fas:/fab: at the start of the label, same on every surface) — not emoji, not icon-nodes. In a type that can’t render them (sequenceDiagram, timeline, gitGraph, C4*, journey, gantt, quadrantChart, requirementDiagram, sankey, xychart), labels stay plain — no fas: token (it leaks or breaks the parse). Colour is monotone-first and paired with an icon or text, never colour alone.
• Flowchart actors are implied by groups or edge labels, not actor nodes (sequence diagrams excepted).
• Node budget ≤ 7; layout is TD unless direction carries meaning.
• Layout fits without extreme scrolling.
• Node IDs are safe.
• Special-character labels are quoted.
• Block openers have matching end lines.
• Arrow syntax matches the diagram type.

Post-Generation Checklist

• Opening keyword is alone on its own line.
• Quotes are balanced.
• No bare < or > inside labels.
• No unexpected visible styling nodes such as class.
• Each path, participant call, or state transition traces correctly.
• Linter exits 0.

Lint Command

python3 ~/.copilot/skills/technical-writing/scripts/mermaid_lint.py /path/to/file.md