d2-diagram

Files (6)

• SKILL.md
• d2-facts.mjs · assets/
• vlmkit-workspace.d2 · assets/
• vlmkit-workspace.facts.json · assets/
• vlmkit-workspace.svg · assets/
• vlmkit-workspace.txt · assets/

SKILL.md (first lines)

# d2-diagram

Paths below: `<skill>` is this skill's directory and `<skills>` the directory the skills are
installed in (`skills/` in mizchi/explainer, `.claude/skills/` in a project that installed them).

A D2 file is the diagram; the picture is a render of it. The writer's job is the
text — ids, labels, containers, connections — and TALA's job is where the boxes
go and how the lines bend. The terminal render exists so the writer reads the
picture on every round without leaving the shell, and so the diagram can live in
a README code block, a PR comment, or a `--help` text.

```d2
direction: right
web: Web frontend
api: API server
db: PostgreSQL {shape: cylinder}
web -> api: HTTPS
api -> db: SQL
```

```
                                                          .-‾‾‾‾‾‾-.
                                                         │╲-______-╱│
                    HTTPS                        SQL     │          │
┌─────────────┐──────────────▶┌───────────┐─────────────▶│          │
│Web frontend │               │API server │              │PostgreSQL│
│             │               │           │              │          │
└─────────────┘               └───────────┘               ╲-______-╱
```

(`d2 --layout=tala x.d2 x.txt`, verbatim, D2 0.8.1-HEAD.)

This skill is for a diagram whose deliverable is **D2 text**: someone will edit
it later, TALA lays it out, and it renders wherever D2 does. When the picture has
to *move* (an algorithm step by step, a walked request) use
`explanatory-animation` / `explain-with-anim` instead. The two combine: draw the
modules and dependencies that `vlmkit-anim facts <dir> --depth 1 --out
f.expect.json` lists, so the D2 is grounded in the code, and keep both files.

## Invocation

```bash
d2 layout                                   # must list `tala (bundled)`. That, not the version
                                            # string, is the gate: v0.8.1-HEAD already bundles it.

d2 --layout=tala arch.d2 arch.txt && cat arch.txt        # the terminal render (Unicode box drawing)
d2 --layout=tala --ascii-mode standard arch.d2 arch.txt  # plain ASCII (+ - | / < > v) for a README
d2 --layout=tala arch.d2 --stdout-format ascii -         # to stdout, for a pipe or a PR comment
d2 --layout=tala arch.d2 arch.svg                        # the figure for docs
d2 --layout=tala arch.d2 arch.png                        # a raster to LOOK at (see the loop, step 5)

d2 validate arch.d2                         # syntax only; exit 1 with file:line:col
d2 fmt --check arch.d2                      # formatted? exit 1 and names the file, changes nothing
d2 fmt arch.d2                              # ...and this rewrites it in place

node <skill>/assets/d2-facts.mjs arch.d2               # what the picture DRAWS
node <skill>/assets/d2-facts.mjs arch.d2 --expect f.json   # ...held to a sheet
LC_ALL=C.UTF-8 wc -L arch.txt               # the width in columns — the locale matters, see below
```

Install when `d2` is missing — never drive the diagram through an online
playground:

```bash
curl -fsSL https://d2lang.com/install.sh | sh -s --      # the installer; it rejects the obsolete --tala flag
brew install d2                                          # macOS
go install github.com/d2lang/d2@latest                   # Go 1.27+; what to do when the install script gets a 403 through a proxy
```

`D2_LAYOUT=tala` in the environment is the same as the flag. `vars: { d2-config:
{ layout-engine: tala } }` inside the file is honoured for `.svg` / `.png` **and
not for `.txt`** on the build measured (0.8.1-HEAD: the text render fell back to
dagre and came out 163 columns instead of 120), so pass the flag anyway; keep the
config in the file so the next person's SVG gets the same engine. A
`sequence_diagram` is the exception that proves the rule — it lays itself out, so
its text render came out byte-identical with and without the flag.

## Nothing in D2 tells you the picture is wrong

`validate` reads syntax. The renderers draw whatever the file says. There is no
`--expect`, no layout report, and **no error for a reference to an id that is not
in scope — it creates a new shape.** So this is a silently wrong diagram:

```d2
edge:    { cdn; gateway }
cluster: { orders; inventory }
gateway -> orders        # ← two NEW empty boxes at the root; the real ones keep no arrow
```

A writer in this skill's own validation round shipped exactly that: `d2 validate`
0, `d2 fmt` clean, 94 columns, and its log said "can trace all connections". The
render had **four duplicated boxes**, two orphans, and the system's entry call
drawn as a floating pair outside every region
([report](https://github.com/mizchi/vlmkit/blob/main/docs/reports/2026-09-14-d2-diagram-v1.md)).

**Write cross-container connections at the root, with full paths.** That is the
one form that always works and the one every writer in the round that got this
right used:

```d2
edge.gateway -> cluster.orders          # at the root: full path on both ends
cluster: {
  billing -> _.outside.stripe           # from INSIDE: `_` is this container's parent
}
```

`_` is **one level and only valid inside a container**. From inside `cluster`,
`_` is the root, so a shape in a sibling container is `_.outside.stripe` — not
`_.stripe`, which invents a root-level `stripe` (that was the round's fourth
phantom). At the root `_` has no parent to mean: `d2` fails the compile with
`invalid underscore`, which a later writer hit and read as the escape being
broken.

`assets/d2-facts.mjs` is the check D2 does not have. It renders the file and
reads the picture back out of the SVG — d2 writes every shape's and every
connection's fully-qualified id into it — so what it reports is what a reader
sees, not what the source seems to say. No dependencies; copy it next to your
diagrams in another repo.

From hasegama/pstack-agents, MIT.

More from hasegama/pstack-agents