Diagram Style

Diagram style

Every diagram on the studio pages is built by a small Python script that
imports diagram_kit.py from this folder. The kit owns the look; a script
only says what is drawn and where. That is what keeps sixteen pictures
looking like one set.

python make_<name>.py                  # writes the .svg beside it
python render_diagrams.py OUT x.svg    # light + dark PNGs, for checking only

The .svg is committed and is what the notes embed. Nothing runs the scripts
automatically: change one, run it, look at the render, commit both.

The vocabulary pictures are built in the rules repo
(docs/vocabulary/make/), which keeps an identical copy of diagram_kit.py.
Edit the copy here, then copy it across.

The rules

Canvas. 760 wide. Nothing but the background card inside the 24 px
margin. Height is whatever the content needs, no dead space at the bottom.

One idea per panel. Two or three panels at most. Panels sit side by side
with a 32 px gap (d.columns(n)) or stack with a separator line.

Colour.

  • Neutrals (s1 s2 s3) draw the objects; lighter is further away.
  • The accent marks the one thing the picture is about: the term being
    defined, the edge being measured, the mistake. Nothing decorative is accent.
  • glass, trim and corner only ever mean the modular roles Insert, Trim
    and Corner. A plain wall or Panel is a neutral.
  • Never write a colour in a script. Use the classes; they switch for dark mode.

Type. Four roles, nothing else:

Class Use
h Panel heading, small caps, one per panel, at its top-left
t / ta A word: the name of a part. ta when it is the word being taught
n / na A short note under a word, or the one-line takeaway
v / va A measured value on a dimension line

Labels. A label sits outside the shape it names, in a column where
possible, and is joined to it by a thin leader with a dot on the thing.
Leaders are straight or one elbow, never cross each other, never cross a
label. d.callout() does the elbow for you.

Words, not paragraphs. A note is a few words. The explanation belongs in
the page around the picture; a diagram carries at most a two-line takeaway.

Done means save() prints no warning, and both renders have been looked
at: nothing clipped, nothing overlapping, nothing that only reads in one theme.