Excalidraw

Excalidraw diagram generator (DSWoK)

Generate .excalidraw.md source files that the Obsidian Excalidraw plugin parses and auto-exports as *.excalidraw.light.svg / *.excalidraw.dark.svg. Notes embed via ![[name.excalidraw.light.svg]].

When to use this skill

Per the diagram tooling order in .claude/writing_style_guide.md:

1. Mermaid for flowcharts, pipelines, dependency graphs, decision trees. Don't use this skill — write Mermaid inline in the note.
2. Excalidraw for everything else (charts, plots, conceptual diagrams, anything with non-grid layout). Use this skill.
3. Hand-authored SVG in images/ only as a fallback when Excalidraw cannot produce the figure cleanly after a couple of iterations.

The skill is meant for vault diagrams. For codebase architecture diagrams or one-off non-vault visuals, write a .excalidraw JSON file directly to /tmp/; this skill's .excalidraw.md wrapper is specifically for the Obsidian plugin format.

Where things live

• Helpers: .claude/skills/excalidraw/helpers.py — Python module with element builders, the .excalidraw.md wrapper, and a dark/light recovery function.
• Source files: write <name>.excalidraw.md to Excalidraw/ in the vault root.
• Auto-generated SVG exports: the plugin writes <name>.excalidraw.light.svg and .dark.svg next to the source after the file is opened in Obsidian once.
• Embeds in notes: ![[<name>.excalidraw.light.svg]] (use the light variant; Obsidian auto-swaps to dark in dark theme via the inverted CSS filter).

Workflow

1. Plan the figure. Sketch the layout (axes, panels, curves, labels, legend) on paper or mentally. Most vault diagrams use a 900×600-ish canvas to match the existing CUPED / Multi-armed-bandits / AB-Tests illustrations. Plot areas typically run from x=110 to x=580 (470 wide) with y=80 (top) to y=510 (bottom, 430 tall).

2. Write a Python script that imports helpers.py and builds an elements list. Run the script to write <name>.excalidraw.md to Excalidraw/. The helper module is at .claude/skills/excalidraw/helpers.py. From a script, import via sys.path.insert(0, "/Users/andreylukyanenko/Documents/DSWoK/.claude/skills/excalidraw"); from helpers import line, text, rect, build_excalidraw_md, ....

3. Tell the user to open the file in Obsidian once. The plugin parses the JSON, renders, and writes the two SVG exports. The first open is mandatory — without it, no SVGs exist and any embed in a note will be broken.

4. Embed the light SVG in the target note. ![[<name>.excalidraw.light.svg]] — never embed the source .excalidraw.md directly.

5. Recovery if only one variant exports. If the plugin only wrote the dark or only the light SVG (e.g., user opened the file in only one theme), call helpers.derive_light_from_dark(...) or its inverse — the only difference between the two exports is a filter="invert(93%) hue-rotate(180deg)" attribute on the root <svg> element.

Helper module API

All helpers live in helpers.py. The most-used:

Module constants: FONT_FAMILY = 5 (Excalifont), ROUGHNESS = 1 (sketchy), accent colors COLOR_RED, COLOR_BLUE, COLOR_GREEN, COLOR_GRAY_LIGHT, COLOR_TEXT_MUTED, COLOR_TEXT_DEFAULT. System-architecture palette is in helpers.PALETTE as (background, stroke) tuples per role.

Example: chart-style figure

import sys, os
sys.path.insert(0, "/Users/andreylukyanenko/Documents/DSWoK/.claude/skills/excalidraw")
from helpers import (line, text, rect, rotate, build_excalidraw_md,
                     COLOR_RED, COLOR_BLUE, COLOR_GRAY_LIGHT)

elements = []

# Title
elements.append(text(280, 30, "Reliability diagram", font_size=28))

# Axes
elements.append(line([(110, 510), (580, 510)], stroke_width=2))  # x
elements.append(line([(110, 510), (110, 80)], stroke_width=2))   # y

# y=x reference (perfect calibration)
elements.append(line([(110, 510), (580, 80)],
                     color=COLOR_GRAY_LIGHT, stroke_width=2, dashed=True))

# Two miscalibration curves
over = [(110, 467), (157, 433), (204, 396), (251, 358), (298, 329),
        (345, 295), (392, 261), (439, 227), (486, 193), (533, 157), (580, 123)]
elements.append(line(over, color=COLOR_RED, stroke_width=3))

under = [(110, 510), (157, 489), (204, 470), (251, 440), (298, 395),
         (345, 295), (392, 195), (439, 150), (486, 121), (533, 101), (580, 80)]
elements.append(line(under, color=COLOR_BLUE, stroke_width=3))

# Axis labels
elements.append(text(280, 555, "Predicted probability", font_size=15))
elements.append(rotate(text(20, 280, "Empirical positive rate", font_size=15), -90))

# Legend
elements.append(rect(620, 120, 240, 130, color=COLOR_GRAY_LIGHT, stroke_width=1))
elements.append(line([(635, 175), (680, 175)],
                     color=COLOR_GRAY_LIGHT, stroke_width=2, dashed=True))
elements.append(text(690, 165, "Perfect calibration", font_size=14))
elements.append(line([(635, 205), (680, 205)], color=COLOR_RED, stroke_width=3))
elements.append(text(690, 195, "Over-confident", font_size=14))
elements.append(line([(635, 235), (680, 235)], color=COLOR_BLUE, stroke_width=3))
elements.append(text(690, 225, "Under-confident", font_size=14))

# Write source
ROOT = "/Users/andreylukyanenko/Documents/DSWoK"
out = os.path.join(ROOT, "Excalidraw/calibration_reliability_diagram.excalidraw.md")
with open(out, "w") as f:
    f.write(build_excalidraw_md(elements))

Example: pipeline / system architecture

For diagrams with labeled boxes and arrows between them, use rect, bind_label, edge_point, and arrow:

from helpers import rect, bind_label, edge_point, arrow, PALETTE, build_excalidraw_md

elements = []

bg, stroke = PALETTE["frontend"]
api_box = rect(100, 230, 180, 80, color=stroke, stroke_width=2, bg=bg)
elements.extend(bind_label(api_box, "API Gateway", font_size=16))

bg, stroke = PALETTE["database"]
db_box = rect(100, 530, 180, 80, color=stroke, stroke_width=2, bg=bg)
elements.extend(bind_label(db_box, "Postgres", font_size=16))

# Arrow from API bottom → DB top (with elbow if needed)
elements.append(arrow(
    [edge_point(api_box, "bottom"), edge_point(db_box, "top")],
    color="#1e1e1e", stroke_width=2, elbowed=False,
))

Coordinate convention

• Top-left origin, like SVG. Larger y is lower on the canvas.
• For line, arrow, and other multi-point elements: pass absolute coordinates. The helper computes the bounding-box top-left as the element's (x, y) and shifts points relative to it.
• Rotation: angle is in radians. Use rotate(element, degrees) to set in degrees.

Pitfalls (these will silently break the file)

Validation before writing

• Every shape with a label has been wrapped via bind_label().
• Multi-point arrows that should have 90° corners have elbowed=True.
• Arrow endpoints are computed via edge_point(...), not eyeballed.
• No duplicate IDs (the global counter handles this; just don't construct elements outside the helpers).
• Every text element uses FONT_FAMILY (= 5) unless there's a specific reason to override.
• For curves on a chart, dense polylines (~10–15 points) approximate smoothness without bezier.

Render and recovery

After writing the source file:

1. Tell the user: "Open Excalidraw/<name>.excalidraw.md in Obsidian once. The plugin will auto-export <name>.excalidraw.light.svg and .dark.svg next to the source."
2. If only one variant gets exported (the user only opened the file in one theme), call derive_light_from_dark() to produce the missing variant.
3. Verify the embed in the target note: ![[<name>.excalidraw.light.svg]].

Output

• Source file: Excalidraw/<name>.excalidraw.md in the DSWoK vault root.
• Generated SVGs: Excalidraw/<name>.excalidraw.light.svg and .dark.svg, written by the plugin after first Obsidian open.
• Note embed: ![[<name>.excalidraw.light.svg]] in the consuming note.

Source: Erlemar/dswok — distributed by TomeVault.