Hand-drawn shapes in plain Typst. No plugin, no dependency, nothing downloaded — just Typst’s own curve.

#import "@preview/scrawl:0.1.0": *

#scrawl-box(fill: rgb("#fffbe6"))[a hand-drawn frame]

The full showcase — 18 figures: line charts, bar graphs, pie charts, Venn diagrams, stick figures, linked diagrams, hatching, roughness levels — each one beside the code that made it. The code shown is the code that ran: the page evaluates the same source it prints, so the two cannot drift apart. It also refuses to compile if a code line grows past the column, because a wrapped line loses its indentation and gets copied wrong.

A scrawled shape is an ordinary Typst element: it measures, nests and flows like any other, so it can sit in a table cell, a grid or a figure. Nothing here loads a WASM binary — which matters if your document has to build on a machine with no network, or if you would simply rather not ship a compiled blob to draw a wobbly rectangle.

The three shortcuts

#scrawl-box(fill: rgb("#fffbe6"))[a frame]
#scrawl-ellipse(paint: green)[circled]
Some #scrawl-underline[underlined] text.

They measure their content, so the frame fits what is inside instead of a size guessed in advance.

The canvas

Coordinates in centimetres, y running up — the way one thinks about a drawing. The body receives the drawing helpers, already bound to the canvas:

#scrawl(width: 15cm, height: 4.5cm,
        (shape, lines, region, rough, label, arrow) => {
  shape(rounded-rect-pts((0.2, 0.2), (4.6, 4.2), radius: 0.35),
    paint: rgb("#2B6CB0"), fill: rgb("#EAF2FB"))
  shape(circle-pts((7, 2.2), 1.6), paint: rgb("#C2410C"))
  arrow((10, 0.5), (14, 3.5))
  label((12, 4.2), [a label])
})

The body receives six helpers, already bound to the canvas:

label and arrow exist so a figure reads like the drawing it is. Positioning text used to mean writing place(dx: 5cm, dy: height - 2cm) by hand — the very conversion scrawl is there to spare you, and getting the sign wrong sent the label off the canvas silently.

Point lists come from rect-pts, rounded-rect-pts, circle-pts and arc-pts, or you write the tuples yourself — a contour is just an array of (x, y).

Hatching

hatching(..) goes where a colour would, because the hatching is the fill:

#scrawl(width: 8cm, height: 3cm, (shape, ..) => {
  shape(circle-pts((1.6, 1.5), 1.3), paint: black,
    fill: hatching(rgb("#2B6CB0"), angle: 45deg, gap: 0.2))
  shape(rect-pts((3.6, 0.3), (5.6, 2.7)), paint: black,
    fill: hatching(rgb("#C2410C"), cross: true))
})

It is a scanline sweep obeying the even-odd rule, so a concave shape hatches correctly and a second contour punches a hole — pass a list of contours and they are treated as one region. The lines wobble by the amplitude of the shape, not their own: otherwise a short segment near a corner would shake harder than the long one across the middle, and the fill would look sorted by length.

Arrows

arrow(from, to, bend: 0.25) curves the shaft, and the head follows the tangent rather than the straight line between the ends — a curved arrow that pointed along its own chord would miss what it points at. bend is relative to the length, so the same value gives the same-looking arc between two neighbouring boxes or across the page.

The head is capped at 55 % of the arrow’s length. Between two boxes 4 mm apart the fixed 0.32 cm head left nothing but a triangle and two pixels of shaft — the diagram in the showcase had exactly that defect.

What you can turn

Two details that make it work

A four-point rectangle cannot look hand-drawn. A rough stroke only deviates where there is a vertex, so a long straight edge stays ruler-straight however high the roughness. Every edge is resampled into ~0.42 cm steps first — that is what makes the effect exist at all.

A hairline must wobble less than an edge, or the deviation is several times the line’s own width and a 0.4 pt rule turns into a scribble. Below 0.9 pt only one pass is drawn, because doubling a thin rule merely doubles the ink and reads as bold rather than as pencil.

By the same reasoning, long edges are damped: a page-tall table rule that shook like a small box would look wrong on a form. That is the default — damping: false turns it off when you are drawing a loose sketch and want the wobble proportional.

Determinism

The same seed produces the same wobble on every compile, so a document builds byte-for-byte identically. A form that reshuffled its own lines between builds would be unusable for anyone who files them.

Under the hood

rough-amp(pts, ..) gives the wobble amplitude of a contour and jitter(paths, ..) displaces point lists — the two halves of the engine, exposed because the hatching needs them and so might you.

Also included

hl(body) — a highlighter swipe behind inline text, drawn with the same pen. Named hl and not highlight so Typst’s own flat-rectangle #highlight stays reachable.

Licence

MIT.

FERGOUS Abdelhak