shenseanchen / excalidraw

Excalidraw whiteboards, Sean's way

Boards are generated from code so they match the masters in ~/Developer/Excalidraw
exactly — Sean films with them directly. Never hand-write .excalidraw JSON; use the
style engine, which locks the values that a from-scratch board always gets wrong.

The five things a naive board gets wrong (all fixed by the engine)

1. fontFamily 5 (Excalifont) — NOT 1 (legacy Virgil). Wrong font = wrong board.
2. roughness 1 (controlled) — NOT 2 (scratchy).
3. Stroke-width hierarchy 1 detail / 2 container / 4 emphasis — not flat 2.

4. Type scale = Excalidraw presets S=16 / M=20 / L=28. Majority is S/M;
   L (28) reserved for big titles only. Don't inflate past the presets.

5. Signature green #b2f2bb, frames, socials block, watermark, source labels.

How to build one

from scripts.whiteboard import style as S   # run from the repo root

e = []
e.append(S.text(60, 40, "Title", size=S.FS_TITLE))
e.append(S.underline(64, 120, 800, color=S.PAL["orange"][1]))
e += S.labeled_box(80, 200, 300, 140, "A box\nwith a note", color="green")
e += S.pill_header(80, 400, 600, "SECTION", color="blue")
e += S.ellipse(500, 200, 180, 120, "agent", color="pink")
e += S.diamond(700, 200, 140, 100, "gate?", color="green")
e += S.labeled_arrow(380, 270, 500, 260, "tool calls")
e += S.socials_block(1980, 44)
e.append(S.watermark(80, 1030))
e.append(S.source_label(80, 900, "per <vendor>, <date>"))   # standing rule
e.append(S.red_note(80, 960, "honest red-ink opinion"))     # standing rule

S.validate(e)                       # catches broken bound-text ids
doc = S.document(e)                 # wraps with appState + white bg

Where the board goes depends on who it is for:

• A board that explains Waku's own code: write it to docs/whiteboards/<name>.excalidraw.

• A board for a video (anything a lab/ topic films): the .excalidraw source and the
  script that draws it go to ~/Developer/Excalidraw/waku-lab/<topic>/, **never into the
  repo**. Commit only a PNG screenshot, to lab/<topic>/screenshots/<name>.png.
  evals/deterministic/test_rulebook.py fails if a .excalidraw file appears in a lab topic.

See lab/kimi-k3/build_k3_tutorial.py for a full two-board example.

Palette (name → fill/stroke), meaning follows Sean's color system

• green loop / hero / final reply · red harness boundary / cost / honest-ink
• blue LLM-ops / observability · orange a loop step · pink LLM/agent nodes
• grey neutral state/config · yellow callout · plain bare container

Always, before delivering

1. S.validate(elements) — every bound text must map to a container.

2. Eyeball via SVG proxy → PNG (QuickLook crops wide canvases; use headless
   Chrome --screenshot --window-size=W,H for the full board). Check for
   overlaps and off-canvas elements.

3. Shareable boards get the socials block + @ShenSeanChen watermark.
4. Every technical/vendor claim gets a dated source_label.

Two ratios, measured from the masters — check yours before delivering

Generated boards fail in the same two ways every time. Both are countable, so
count them instead of eyeballing:

# against ~/Developer/Excalidraw/<newest>.excalidraw
black strokes / all shapes   ->  masters: 96%   (354 of 368)
arrows / all shapes          ->  masters: 0.88  (241 arrows, 165 ellipses)

1. COLOUR POLLUTION. The masters are ~96% BLACK strokes with transparent or
   white fills. Colour lands maybe fifteen times on a whole board: green
   #b2f2bb for the hero, red #ffc9c9 for the warning, and a handful of
   coloured strokes on section boundaries. A first-pass generated board
   typically comes out at 3% black — a coloured stroke on every shape. Ink by
   default; a fill has to earn its place. Note labeled_box(fill="chip") is
   documented as user-prompt/reply chips ONLY, and using it for general boxes
   is the usual cause.

2. NO FLOW. The masters average nearly one arrow per shape, with ellipses
   for agents and diamonds for decisions. A board of boxes in a grid with two
   arrows is an infographic, not a whiteboard — it reads as dead. If the
   subject has motion, DRAW the motion: fan-outs, back-edges, branches from a
   diamond. A back-edge that visibly returns is worth more than a paragraph.

Fix both before showing it, because they are the first things Sean notices.

Layout lessons (from comparing generated vs. hand-drawn)

• Poster-tight beats sprawl for a single teaching idea — fit it in one landscape
  frame (~2500×1100) so it reads without panning. Reserve the 8000×20000 sprawl
  for full system maps.

• A diagonal "ladder" reads as progress; a red barrier + a green break-through
  reads as problem→solution. Reuse those two shapes.