| name | diagram-studio |
| description | Use when creating architecture, sequence, class, ER, or state diagrams as Mermaid for GitHub docs or editorial HTML for client decks; includes verify and drift against codebase |
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.
| If showing… | Use | Reference |
|---|
| Components + connections | flowchart | cheatsheet.md#flowchart |
| Messages over time | sequenceDiagram | cheatsheet.md#sequence |
| States + guards | stateDiagram | cheatsheet.md#state |
| Entities + fields | erDiagram | cheatsheet.md#er |
| Classes + ops | classDiagram | cheatsheet.md#class |
Full 39-type editorial taxonomy from cathrynlavery/diagram-design is mapped to these 5 Mermaid types — 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  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.
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 mermaid_verify 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, mermaid_verify/mermaid_drift mention | 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, mermaid_verify 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 is case-complete — 5 diagram types × 2 audiences × 3 outputs × 3 verifications, all live-verified (packages/dsh-maestro-diagram 8/8, maestro-workspace -r verify 13 Done). See references/supported-cases.md for the full tables.
| # | Mermaid type | When to use | Audience variants | Output |
|---|
| 1 | flowchart TB/LR | Components + connections | Team: harness-architecture.html 16K (svg+pre) → Client: ...-client.html 12K (svg only) | docs/architecture.md §1.1 + HTML + PDF p1 |
| 2 | sequenceDiagram | Messages over time | Team: harness-turn-flow-sequence.html 31K → Client: ...-client.html 30K | docs/specs/...-sequence.md + HTML + PDF p2 |
| 3 | classDiagram | Classes + ops | Team/Client per Audience Rules | cheatsheet.md#class |
| 4 | erDiagram | Entities + fields | Team/Client | cheatsheet.md#er |
| 5 | stateDiagram | States + guards | Team/Client | cheatsheet.md#state |
All 5 share tokens paper/ink/accent/muted/link (no shadow, rx:6, accent 1-2). Verification: mermaid_verify 5/5 PASS, mermaid_drift missingInCode 0, strict warns on shadow:true. Details and live case studies in references/supported-cases.md.
Verify & Drift
Always call mermaid_verify before commit — it runs mermaid.parse() + optional mermaid-cli validate and returns {ok, errors, warnings}. Never commit a diagram that fails parse. Anti-patterns (e.g. shadow, graph legacy) are reported as warnings in strict mode.
Run drift check before PR: mermaid_drift --diagram docs/architecture.md --roots packages/*,govard/internal/*,maestro-skills/skills to flag missingInCode / staleEdges / missingInDiagram against the codebase (inspired by diagram-drift). Fix drift by patching the doc or the code reference.
CLI fallback when the plugin is not installed: node maestro-skills/skills/diagram-studio/scripts/verify-mermaid.mjs docs/architecture.md or node scripts/verify-mermaid.mjs <file|->.
