Diagram Studio

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

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

| # | 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: 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.

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