Diagram Studio

Hybrid Mermaid + editorial HTML for architecture, sequence, class, ER, and state diagrams.

When to Use

Use when the reader learns more from a visual than from a paragraph or table. Ideal for system architecture, message flows over time, entity relationships, class structures, and state transitions with guards.

Don't use for simple lists, single before/after comparisons, or a one-sentence relationship that a table can express — use a table instead.

Selection

Choose the Mermaid type by the semantic pattern, not by habit. See references/cheatsheet.md for minimal examples.

Full 52-ordinal editorial taxonomy from cathrynlavery/diagram-design v2.6.32 is mapped to these 5 Mermaid types in references/supported-cases.md (mapped or explicitly out of scope) — start with the table above before inventing a new form.

GitHub-compatible Mermaid style: use flowchart TB or flowchart LR (never legacy graph), add classDef tokens from references/style-guide.md, and use linkStyle/style sparingly for the focal path.

flowchart TB
  A["Client"] --> B["Cordis"]
  classDef focal fill:#eb6c36,stroke:#2d3142,color:#fff
  class A focal

Editorial Discipline (from diagram-design)

Extracted from cathrynlavery/diagram-design — see references/diagram-design-learnings.md:

• Density 4/10 — generous whitespace, no wall of boxes. Every node must earn its place.
• >9 nodes → split into overview + detail diagrams rather than cramming.
• Accent 1-2 max — use classDef focal fill:#eb6c36,stroke:#2d3142 for the single hot path; all other nodes stay paper/muted. No shadows (shadow:false), rx:6 max, mono only for ports/URLs.
• Confirm before drawing — state type, size preset (85%/100%), what will be cut due to budget and wait for redirect if the user is reachable. Never assume the diagram scope.

Where to Write

• docs/ARCHITECTURE.md §1.1 — single source for the umbrella architecture (do not duplicate elsewhere).
• docs/specs/*-design.md — for RFC/spec diagrams; each spec may embed one Mermaid block that lives with the design.
• docs/diagrams/<slug>.html — for editorial export (optional, self-contained HTML+SVG for client decks). Link preview via ![Preview](diagrams/<slug>.html) in markdown when needed. Use spacing tokens from references/style-guide.md#deck-html-layout-tokens (header 16px, line-height 1.6) so deck text isn't cramped — verify with grep line-height.
• docs/diagrams/maestro-harness-deck.html — 3-page A4 deck (cover + 2 diagrams). Must use deck layout tokens above; header flowchart TB and 10 plugins + meta must have 8px gap, not flowchart TB10.

Add docs/diagrams/.gitkeep if the folder is otherwise empty. The harness-* and maestro-harness-deck files named in this skill and in references/ are historical examples from the original harness repo; they are not shipped with this plugin.

Audience Rules (what to show for Team vs Client)

Every diagram has two audiences. The skill MUST decide on audience before writing docs/diagrams/<slug>.html (default is team when not specified — ask 1 line if unclear). Use this exact checklist:

| Element | Team / Internal (audience: team|internal|engineering|review or prompt has "cho team / keep source / để team xem") | Client / External (audience: client|pitch|deck|external or prompt has "cho khách / clean deck / bản đẹp cho khách") | |---|---|---| | Rendered diagram (inline SVG, self-contained, no JS) | Yes — always | Yes — always | | Mermaid source ```mermaid | Yes — inside <details><summary>Mermaid source</summary><pre class="mermaid">…</pre></details> collapsed by default (so the verifier can re-check, GitHub diff preserved) | No — remove <pre> and <details> entirely | | Editorial tokens card (paper/ink/accent swatches, hex) | Yes — keep the "Editorial tokens" card (so team knows palette to maintain) | No — remove the whole card (client only needs the diagram, not the design system) | | Technical footer (file path, verify {"ok":true}, drift missingInCode 0, generation note) | Yes — keep the "About this export" card with Source: docs/..., verify/drift line | No — remove or reduce to 1 line: Generated via diagram-studio — 2026-08-27 (no file paths, no verify/drift) | | Styling | Full tokens paper/ink/accent/muted/link as in references/style-guide.md | Same tokens (visual stays identical) — only the meta cards differ |

Rules for other locations (not audience-driven):

• docs/ARCHITECTURE.md and docs/specs/*-design.md — always show source as ```mermaid block (GitHub renders it, diffable, single source of truth, verification checks it) — audience rule does not apply here.
• docs/diagrams/*.pdf deck — always client rules (hide source, hide tokens card, hide technical footer, use PNG only) — PDF is for distribution.

When audience is ambiguous, default to Team (show everything collapsed) and add a 1-line note: "Hiding source/tokens for client — say 'clean for client' to hide."

Supported Cases (summary — details in references/supported-cases.md)

This skill covers 5 diagram types × 2 audiences × 3 outputs. Parse and strict checks run through the bundled CLI (scripts/verify-mermaid.mjs); drift against the codebase is checked by hand. See references/supported-cases.md for the full tables.

All 5 share tokens paper/ink/accent/muted/link (no shadow, rx:6, accent 1-2). Verification: parse passes for all 5 types, --strict warns on shadow:true. Details and live case studies in references/supported-cases.md.

Verify & Drift

Always verify before commit: a diagram that fails parse must never ship. Run the bundled CLI, which extracts every mermaid block and checks each one on its own. It runs the real mermaid.parse() when mermaid and jsdom can be imported from the script (for example npm i --no-save mermaid jsdom in the repo checkout) and returns {ok, errors, warnings, validator} with validator: "mermaid". Without them it falls back to a heuristic (incomplete arrows, unterminated strings, unclosed flowchart brackets), reports validator: "heuristic" and a warning, and a heuristic ok is not a syntax guarantee: use --require-parser to refuse that mode (exit 2). It exits 0 on success and 1 on failure. Add --strict to report anti-patterns (e.g. shadow, legacy graph) as warnings.

node maestro-skills/skills/diagram-studio/scripts/verify-mermaid.mjs docs/ARCHITECTURE.md --strict
node scripts/verify-mermaid.mjs <file|-> --strict   # from this repo's root, or '-' for stdin

Drift is done by hand, with no tool behind it. Before a PR, compare the diagram against the codebase and flag missingInCode / staleEdges / missingInDiagram (inspired by diagram-drift): every node must map to a real package, file or service, and every real component in scope must appear. Fix drift by patching the doc or the code reference.