Diagrams#

Generate diagrams from structured JSON → SVG (and optionally PNG).

Quick Start#

1. Install elkjs in the target directory (if not already present): bash

   cd <project>/docs/diagrams && npm init -y && npm install elkjs
   # Set "type": "module" in package.json
   
   

2. Write ELK JSON files describing the diagram (see schema below)

3. Render: bash

   # Single file
   node <skill-dir>/scripts/render-elk.mjs diagram.json output.svg
   
   # Batch: all .json files in a folder → svg/ subfolder
   node <skill-dir>/scripts/render-elk.mjs --dir <folder>
   
   # Batch + PNG (macOS only, uses sips)
   node <skill-dir>/scripts/render-elk.mjs --dir <folder> --png
   
   

4. Embed in markdown: markdown

   ![Diagram Title](diagrams/svg/my-diagram.svg)
   
   

ELK JSON Schema#

json

{
  "id": "root",
  "title": "Diagram Title (rendered as heading)",
  "layoutOptions": {
    "elk.algorithm": "layered",
    "elk.direction": "DOWN",
    "elk.spacing.nodeNode": "30",
    "elk.layered.spacing.nodeNodeBetweenLayers": "40",
    "elk.padding": "[top=40,left=20,bottom=20,right=20]"
  },
  "children": [
    {
      "id": "node1",
      "width": 220,
      "height": 45,
      "labels": [{"text": "Node label for ELK layout"}],
      "label": "📦 Display label (rendered in SVG)",
      "color": "core",
      "subtitle": "Optional second line"
    }
  ],
  "edges": [
    {
      "id": "e1",
      "sources": ["node1"],
      "targets": ["node2"],
      "labels": [{"text": "Yes", "width": 25, "height": 14}],
      "edgeColor": "#10B981",
      "dashed": true
    }
  ]
}

Node Properties#

PropertyTypeDescriptionidstringRequired. Unique identifierwidthnumberNode width in px (default 120)heightnumberNode height in px (default 40)labelsarray[{text}] — used by ELK for layout calculationlabelstringDisplay text rendered in SVG (supports emoji). Falls back to id``colorstringColor key from palette (see below)subtitlestringSmaller text below the labelfontSizenumberLabel font size (default 13)childrenarrayNested nodes — makes this a containercontainerColorstringColor key for container background

Edge Properties#

PropertyTypeDescriptionidstringRequired. Unique identifiersourcesstring[]Source node id(s)targetsstring[]Target node id(s)labelsarray[{text, width, height}] — edge labelsedgeColorstringHex color (default #64748B)dashedbooleanDashed line stylestrokeWidthnumberLine thickness (default 1.5)

Color Palette#

8 semantic colors. Every node maps to one. A legend auto-renders at the bottom of each SVG.

KeyColorMeaningUse Foraction🔵 BlueSystem actionSteps the app performs — API calls, DB writes, cron triggersexternal🟢 TealExternal serviceThird-party APIs — Google, Twilio, Stripe, Resenddecision🩷 PinkDecision pointYes/no branches, if/else, conditional checksuser🟠 OrangeUser actionThings the user does — clicks, inputs, reviewssuccess🟢 GreenPositive outcomeDone, confirmed, created, visiblenegative🔴 RedNegative outcomeCanceled, error, failed, not builtneutral⚫ GrayNeutral / infoStarting points, labels, inactive, informationaldata🟡 AmberData / artifactRecords, drafts, outputs, intermediate data

Set "legend": false on the root graph to hide the auto-legend.

Layout Options#

Common layoutOptions values:

• elk.direction: DOWN (default), RIGHT, LEFT, UP
• elk.algorithm: layered (default, best for flowcharts), force, stress
• elk.spacing.nodeNode: Space between sibling nodes (px)
• elk.layered.spacing.nodeNodeBetweenLayers: Space between layers (px)
• elk.padding: [top=N,left=N,bottom=N,right=N]

Design Tips#

• Sizing: 200-280px wide for most nodes. 45px tall for single-line, 55px for two-line labels.
• Decision nodes: Use context (pink) color for yes/no branching.
• Edge labels: Keep short (Yes/No/Error). Set width/ height for proper positioning.
• Containers: Add children array to a node. Use containerColor: "step" for a light blue group.
• Manual trips vs automated: Use dashed: true on edges for alternative/optional paths.
• Title: Set title on the root graph for a rendered heading above the diagram.
• Emoji in labels: Supported and encouraged for visual scanning.

Gotchas#

• Container layout: ELK's layered algorithm with nested containers in RIGHT direction can produce overlapping layouts. Prefer DOWN for containers, or flatten to a non-container layout if horizontal.
• labels vs label: labels (array) is what ELK uses for layout spacing. label (string) is what gets rendered in the SVG. Always set both — labels[0].text should approximate the display label length for correct sizing.
• package.json must have "type": "module" for the ESM import to work.
• elkjs must be installed locally in the directory where you run the script. It's not global.