creating-diagrams

Files (13)

• CHANGELOG.md
• SKILL.md
• login-sequence.d2 · examples/
• request-path.d2 · examples/
• retry-decision.d2 · examples/
• trust-boundary.d2 · examples/
• d2-essentials.md · references/
• design.md · references/
• layouts.md · references/
• text-alternatives.md · references/
• creating-diagrams.mjs · scripts/
• tools.mjs · scripts/
• creating-diagrams.test.mjs · tests/

SKILL.md (first lines)

# Creating diagrams

Turn a description of what a diagram must show into D2 source, a rendered SVG, and alt text, then prove it is readable where it will be shown.

Script paths below are relative to this skill's folder. Run each as one command with the folder's absolute path in front, never chained with `&&`, `$(…)`, or heredocs.

## Inputs

- **What it must show**: the message, the subjects, and the relationships. In a slide deck this is the slide's Visual Intent.
- **Output path** for the `.svg`. The PNG and ASCII previews are written beside it.
- **Theme values** (optional): a JSON file of CSS custom properties (`--color-bg`, `--color-text`, `--color-surface`, `--color-muted`, `--color-accent`, `--color-on-accent`). Without one, a neutral palette is used.
- **Slot size** (optional): the space the diagram will fill, in px on a 1280×720 reference, as `WIDTHxHEIGHT`. The default is a 16:9 slide's content area, `1164x616`.

## Workflow

Copy this checklist and tick it off:

```
- [ ] 1. D2 is installed
- [ ] 2. One message stated
- [ ] 3. D2 written with Diagram Roles
- [ ] 4. check passes
- [ ] 5. render written and the PNG looked at
- [ ] 6. Alt text written
```

1. Run `node scripts/creating-diagrams.mjs setup --status`. If D2 is missing, ask the person to run `node scripts/creating-diagrams.mjs setup` once, outside the sandbox. It downloads the pinned D2 with a verified checksum into a shared cache.
2. Write the diagram's one message as a comment on the first line, for example `# One message: only the API crosses the network boundary.` Split anything that needs two messages into two diagrams.
3. Write D2 that styles every shape and connection with a **Diagram Role** (`class: <role>`) only, never colours or font sizes:

   | Role | Use for |
   |---|---|
   | `base` | ordinary shapes |
   | `emphasis` | the one or two shapes the message is about |
   | `muted` | context that matters less |
   | `risk` | failure, danger, or cost |
   | `boundary` | containers such as networks or teams (dashed) |
   | `flow` | ordinary connections |
   | `optional-flow` | conditional or fallback paths (dashed) |
   | `risk-flow` | failure paths |

4. Run `node scripts/creating-diagrams.mjs check <file.d2> [--theme <values.json>] [--slot WxH]`. Fix every reported problem and run it again until it passes. A legibility failure names the fix: change direction, shorten or wrap labels, or split the diagram.
5. Run `node scripts/creating-diagrams.mjs render <file.d2> --out <file.svg> [--theme <values.json>] [--slot WxH]`. Look at the `.png` preview, and check that every label in the reported **Labels** list belongs to the diagram. A green check is not proof: rendered layouts can still mislead.
6. Write the alt text, and a long description when the diagram carries more than one sentence of information. See [references/text-alternatives.md](references/text-alternatives.md).

## Rules agents most often miss

These compile without any error yet produce the wrong diagram:

- Quote any label containing `#` (it starts a comment) or `;` (it splits the shape in two). The `check` command catches these.
- Connect **keys**, not labels: `api -> db`, not `API service -> Postgres`, which creates new shapes.
- Inside containers, connect by full path (`public.user -> private.api`). A short name outside its container creates a new top-level shape.
- In a sequence diagram, declare every actor before any group. An actor first seen inside a group turns the group into an actor.
- Keep about four shapes per row. Legibility comes from layout, not font size.
- Never add a legend. Put meaning in labels and role styles.

## References

- **D2 syntax and silent pitfalls**: [references/d2-essentials.md](references/d2-essentials.md)
- **Choosing direction, layout engine, and when to split**: [references/layouts.md](references/layouts.md)
- **Diagram design (one message, labels, colour by role)**: [references/design.md](references/design.md)
- **Alt text and long descriptions**: [references/text-alternatives.md](references/text-alternatives.md)
- **Verified examples** (each passes `check`): [examples/](examples/)

For icons, imports, layers, animation, SQL tables, UML classes, and LaTeX, query the installed D2 (`d2 --help`, `d2 layout`) or read [d2lang.com](https://d2lang.com) rather than guessing syntax.

From ken-guru/skills, MIT.

More from ken-guru/skills