Skip to content

User guide

The tutorial builds one figure end to end, and the how-to guides give a recipe per kind of figure. This guide takes the pieces one at a time — it is organised by mechanism rather than by outcome.

The shape of a figure

Everything in svg-plus is one of four things.

What it is Examples
Blocks Things that state their height and then draw themselves Text, Frame, Stack, Row, Bars
Theme Fonts, palette and spacing, inherited by every block Theme, TextStyle, Font
Doc The figure: a width, a theme, a list of blocks, an output file Doc
Canvas The drawing surface, and the escape hatch Canvas, Rect, Draw

A figure is built in three passes, and knowing the order explains most of the API:

  1. Measure. Every block is asked how tall are you at this width? Containers add up what their children answer.
  2. Arrange. The document cuts a canvas to the total and hands each block the rectangle it asked for.
  3. Render. Blocks emit SVG in the coordinates they were placed at.

Because measuring comes first, a block never has to know where it is — and you never have to tell it.

The chapters

  • Laying out

    Stack, Row, Frame, Spacer, grid(). Fixed columns, flexible slack, and how heights are decided.

  • Setting text

    Text, alignment, leading, tracking. What total-fit line breaking does and when to reach for hyphenation.

  • Fonts and themes

    Loading real fonts, naming colours instead of spelling them, and restyling a figure by swapping one object.

  • Drawing and output

    Draw and the Canvas primitives, connectors between named blocks, and writing SVG, PDF or PNG.

Conventions used throughout

Colours are named. Any string that is not #rrggbb or "none" is looked up in the theme: the palette roles ink, muted, accent, surface, rule, page, then the status colours red, amber, green, blue, grey. An unknown name raises KeyError rather than silently drawing something grey.

Sizes are units, not pixels. The SVG carries a viewBox, so a figure scales to wherever it lands.

None means "inherit". Numeric options — size, leading, pad, radius, gap — default to None and fall back to the theme. Pass a number to override just that one.

Composites are functions, not classes. card(), band(), heading(), eyebrow() and grid() return ordinary blocks assembled from the primitives. Read their source when you want to know what they do; copy it when you want something slightly different.