---
name: create-diagrams
description: Use when a coding agent needs to create or update interactive software architecture or workflow diagrams with Better Diagrams.
---

# Create diagrams

Author diagram source. Better Diagrams supplies layout, exploration, editing, and export.

Use the bundled CLI with Node.js 22.18 or later. Resolve `bin/cli.mjs` relative to this `SKILL.md` and replace that path in the commands below with its absolute installed path. Keep the user's working directory: project and output paths resolve from there. The skill includes its runtime and needs no npm installation. If the bundled CLI is missing, report an incomplete skill installation.

For a new diagram, establish its purpose, audience, visible scope, and detail level. Reuse choices already supplied or approved. If a consequential choice is missing, propose it before authoring.

Read [the source format](references/source-format.md). Start from [the minimal example](assets/minimal-diagram.json) when useful. Inspect the relevant code and callers; record paths and line numbers that support the diagram. Add a verified HTTP(S) permalink when available.

Create new diagrams with source version 2. Use `architecture` for components and their relationships, or `flowchart` for actions, decisions, and outcomes. Keep an existing version 1 document at version 1 unless its upgrade is requested. Sequence, state machine, entity relationship, and dependency graph are catalog entries with no renderer yet.

Create `diagram.json` in the chosen directory. Use stable canonical node IDs, short titles and summaries, named views, and `childViewId` for deeper structure. Put full explanations and verified evidence in details. Each flowchart view declares its step kinds and an ordered main path of **edge IDs**. Architecture connections have a kind and a clear label. Flowchart `next` connections have no label; branches, errors, retries, and jumps have labels.

The compiler places nodes and routes connections; the source has no coordinates. Define nested boundaries with direct node membership and `parentId`. Put optional CSS in `theme.css`, inert architecture components in `templates/`, and local SVG logos in `logos/`. A node's `logo` selects the filename without `.svg`. Use concise text that fits the fixed presets; the default architecture component truncates overflowing summaries and keeps the complete text available in its modal.

| Command | Result |
| --- | --- |
| `node bin/cli.mjs check PROJECT` | Validate document structure and asset paths |
| `node bin/cli.mjs build PROJECT --out FILE.html` | Create self-contained HTML |
| `node bin/cli.mjs dev PROJECT` | Start local editing and watch diagram files; report the printed URL |

Run check and build after authoring. These commands do not verify rendering. If browser access is available, open the artifact and check fixed text bounds, labeled routes, details, modal Back/Close, and Export SVG/Export PNG after pan/zoom. Use Fit or Search when a node is outside the readable initial viewport. Search matches names, IDs, summaries, and source paths in the active view; selecting a result reveals and focuses the node without opening details. If browser launch is denied or unavailable, return the artifact with rendering marked unverified. Built HTML contains only the diagram and optional legend, with on-demand controls. Details and internal views use one modal. SVG and PNG exports contain the complete active diagram and optional legend, excluding the modal, outer views, Search, and controls. PNG targets 2× resolution within fixed size limits described in the source-format reference. Inspect the actual PNG before claiming its fonts or appearance are verified. Routing is a bounded heuristic with an ELK fallback, not a guarantee of a global optimum.

If your host's browser automation supports script evaluation, run `await window.betterDiagrams.inspect()` in the built HTML. It returns a structured geometry report for every authored view, including hidden views. Correct reported errors and inspect warnings; a necessary detour can remain a warning. A passed report can contain warnings and does not establish visual readability or source accuracy. Report geometry checks separately from observed interaction/visual checks. Rebuild after source changes before inspecting again. If the API or browser is unavailable, report geometry checks as unverified; do not infer a pass from `check` or `build`.

Return actual source/artifact paths, the selected purpose/detail, and observed checks. Diagram data, CSS, templates, and logos update the live editor. Application-code changes require regenerating diagram source.