Brainforge Knowledge

d2-diagrams-setup

2 min read

D2 Diagram Workflow Setup

Use this workflow when a diagram should be versioned as text, rendered cleanly in GitHub via an image embed, and optionally polished for platform.brainforge.ai.

What This Adds

The repo includes a root script at scripts/render-d2-diagrams.mjs with package scripts:

npm run diagrams:render -- <path-or-dir>
npm run diagrams:preview -- <path-or-dir>
npm run diagrams:publish -- <path-or-dir>

Install

Install the required CLI:

brew install d2

For PNG preview renders used in visual inspection:

brew install librsvg

Verify:

which d2
which rsvg-convert

Preview bitmaps are local inspection artifacts and should not be committed. The repo ignores *.render.png.

Repo Convention

Use three artifact levels when needed:

  • topic.d2 — editable source
  • topic.generated.svg — direct D2 CLI output
  • topic.svg — optional polished/published SVG when Brainforge branding or manual layout refinement is needed

For quick internal diagrams, the generated SVG is often enough.

For polished external or long-lived diagrams, keep the generated SVG as the raw baseline and treat the published SVG as the branded artifact.

Commands

Render generated SVGs:

npm run diagrams:render -- knowledge/engineering/diagram-examples/system-flow.d2

Render generated SVGs and PNG previews for visual inspection:

npm run diagrams:preview -- knowledge/engineering/diagram-examples/system-flow.d2

Publish directly to topic.svg:

npm run diagrams:publish -- knowledge/engineering/diagram-examples/system-flow.d2

Render every D2 file in the repo:

npm run diagrams:render -- --all

Review Loop

For important diagrams:

  1. Render the D2 file to topic.generated.svg
  2. Generate a PNG preview with npm run diagrams:preview -- ...
  3. Visually inspect the bitmap for spacing, label collisions, and balance
  4. If needed, create or refine topic.svg as the branded published version

Branding Guidance

Follow the Brainforge diagram rule and brand sources:

  • .cursor/rules/brainforge-diagram-standards.mdc
  • knowledge/standards/03-knowledge/brand-style-guide.md
  • apps/platform/src/lib/analytics/decks/themes/brainforge.ts
  • apps/marketing-site/src/styles/tokens.css

Example

See:

  • knowledge/engineering/diagram-examples/system-flow.d2
  • knowledge/engineering/diagram-examples/system-flow.generated.svg
  • knowledge/engineering/diagram-examples/system-flow-d2.svg
  • knowledge/engineering/diagram-templates/

Graph View